mach_examples/llms-full.md

# MACH

C23 web framework. App = `config mach()` returning `(config){...}` of resources, databases, modules. Each request runs a pipeline of steps over a per-request context. Memory, threads, I/O managed by the framework. Tasks and events are durable.

---

## CRITICAL RULES — read before writing any code

### Rule 1 — NEVER use `.` between `{{` and `}}`

`{{a.b}}` renders empty. Always use sections to enter nested scope: `{{#name}}...{{/name}}`. Template shape mirrors context shape.

**Helpers use `:` not `.` — these are fine:** `{{url:name}}`, `{{input:title}}`, `{{error:title}}`, `{{precision:total:2}}`.

#### Pattern A — Single root scalar

```c
.context = {{"site_name", "MACH App"}}
```
```html
✅ <h1>{{site_name}}</h1>
```

#### Pattern B — `query()` / `find()` result is a TABLE, even single-row

```c
find({.set_key = "todo", .db = "todos_db",
  .query = "select id, title from todos where id = {{id}};"})
```
Context: `{ todo: [{id: 5, title: "Learn MACH"}] }`. Open the section to read fields:
```html
✅ {{#todo}}<h1>{{title}}</h1>{{/todo}}
❌ {{todo.title}}             dot — renders ""
❌ <h1>{{title}}</h1>         not inside #todo — renders ""
```

#### Pattern C — After `join()`: parent + nested children (most common; most-failed)

`query()` produces sibling tables. `join()` **MOVES** children inside parents — children no longer exist at root.

```c
query(
  {.set_key = "project", .db = "projects_db",
   .query = "select id, name from projects where id = {{id}};"},
  {.set_key = "tasks",   .db = "projects_db",
   .query = "select id, project_id, title from tasks where project_id = {{id}};"}
),
join(.target_table_key="project", .target_field_key="id",
     .nested_table_key="tasks", .nested_field_key="project_id",
     .target_join_field_key="tasks"),
```
Context after join: `{ project: [{id, name, tasks: [{id, project_id, title}, ...]}] }`. Tasks are now INSIDE project.

```html
✅ {{#project}}
     <h1>{{name}}</h1>
     <ul>{{#tasks}}<li>{{title}}</li>{{/tasks}}</ul>
   {{/project}}
```

**❌ Every one of these renders empty:**
- `{{project.name}}` — dot
- `{{project.tasks.title}}` — dot
- `{{#project.tasks}}...{{/project.tasks}}` — dot in section name
- `{{#tasks}}<li>{{title}}</li>{{/tasks}}` — at root after join, tasks lives inside project, not at root
- `<h1>{{name}}</h1>` then `{{#tasks}}...{{/tasks}}` separately — name is inside project record too; no partial entry. **EVERY field that came from `set_key="X"` requires `{{#X}}` first**, including the parent's own scalars.

**Rule of thumb:** if a field came from `query().set_key = "X"`, it must be inside `{{#X}}`. No partial entry — you're inside the section or at root.

#### Pattern D — 3+ levels nested

`{ org: [{name, projects: [{title, tasks: [{label}]}]}] }`:
```html
✅ {{#org}}{{name}}{{#projects}}{{title}}{{#tasks}}{{label}}{{/tasks}}{{/projects}}{{/org}}
❌ {{org.projects.tasks.label}}    dot
❌ {{#org.projects}}...             dot in section name
```

#### Pattern E — Iteration: `{{#name}}` auto-loops when name is array

```c
{ projects: [{title:"A", tasks:[{label:"x"}]}, {title:"B", tasks:[{label:"z"}]}] }
```
```html
✅ {{#projects}}<li>{{title}}<ul>{{#tasks}}<li>{{label}}</li>{{/tasks}}</ul></li>{{/projects}}
```

#### Template Checklist — run on every `{{...}}` BEFORE emitting

0. **Well-formed:** exactly two `{` and two `}`, no whitespace inside delimiters. `{{/x}` (one `}`), `{x}}`, `{{{x}}}`, `{ {x} }` are all broken. After typing every `{{/...}}`, count the closers: `}` `}`.
1. **No dot:** any `.` between `{{` and `}}` → STOP, add a section.
2. **Field reachable:** is the bare name at the current scope? At root, only top-level keys. Inside `{{#X}}`, only fields of `X`'s record. After `join(child→parent)`, child no longer at root — must be inside `{{#parent}}`.
3. **Depth = wrappers:** N nesting levels = N section pairs.
4. **Section balance + nesting:** every `{{#x}}` has exactly one `{{/x}}` later, and vice versa. Sections nest like parens, never overlap. `{{#a}}{{#b}}{{/a}}{{/b}}` is broken even though counts match. Each named section opens **once** in a given scope.

---

### Rule 2 — ONE database per DOMAIN, not one per table

A "domain" is **what one MODULE owns** — a feature slice — not a noun in your data model.

A `projects` module owns *everything* about projects: project records, tasks attached to them, comments on those tasks, tags. **All of that lives in ONE database** (`projects_db`) with **many migrations** (one per table). Tasks aren't their own domain just because "tasks" is a noun — they're part of projects because they belong to projects.

**A new database appears only when a new module appears.** New table inside the existing module → new migration in the existing db, NOT a new db.

#### ✅ Correct
```c
.databases = {{
  .engine = sqlite_db, .name = "projects_db",
  .connect = "file:projects.db?mode=rwc",
  .migrations = {
    "CREATE TABLE projects (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL);",
    "CREATE TABLE tasks (id INTEGER PRIMARY KEY AUTOINCREMENT,"
      "project_id INTEGER NOT NULL REFERENCES projects(id), title TEXT NOT NULL);",
    "CREATE TABLE comments (id INTEGER PRIMARY KEY AUTOINCREMENT,"
      "task_id INTEGER NOT NULL REFERENCES tasks(id), body TEXT NOT NULL);"
  }
}}
```

#### ❌ Wrong — both forms

```c
// Form A: one db per table
.databases = {{...projects_db...}, {...tasks_db...}, {...comments_db...}}

// Form B (subtler, most common): parent + child split into separate dbs
.databases = {{...projects_db (with projects only)...},
              {...tasks_db (tasks should live in projects_db)...}}
query({.db = "projects_db", ...}, {.db = "tasks_db", ...})  // wrong db
```

**Parent-child relations are ONE domain, ONE database.** project+tasks, blog+comments, order+line_items, user+sessions, todo+comments — all one domain each. If `child` has `parent_id REFERENCES parent`, they belong in the same db.

**Rationalizations to REJECT:**
- *"X and Y are different concepts so they should be different domains"* → Wrong. The foreign-key relation IS what makes them one domain.
- *"More normalized / cleaner separation"* → MACH's separation unit is the **module**, not the table.
- *"Microservices use one db per service"* → Right analogy, wrong unit. In MACH, "service" = module, not table. One module = one db.
- *"My data model has X entities so I need X dbs"* → No. Number of dbs = number of modules. A module owns 3–10 tables.

**Self-check before adding a 2nd `.databases` entry:** "Am I adding a new module?" If no, you don't need a new db — add a migration to the existing one.

---

### Rule 3 — Concurrent queries: ONE step, MANY items (works across dbs too)

`query()` and `fetch()` items run in parallel. Two separate `query()` steps run **serially**. If items don't depend on each other, put them in ONE step.

```c
✅ // Same db, concurrent
query(
  {.set_key="todos", .db="todos_db", .query="select id, title from todos;"},
  {.set_key="count", .db="todos_db", .query="select count(*) as n from todos;"}
)

✅ // Across dbs — STILL one step, still concurrent
query(
  {.set_key="user",     .db="users_db",    .query="..."},
  {.set_key="orders",   .db="commerce_db", .query="..."},
  {.set_key="activity", .db="activity_db", .query="..."}
)

❌ // Three serial round-trips for independent queries
query({.set_key="user", .db="users_db", ...}),
query({.set_key="orders", .db="commerce_db", ...}),
query({.set_key="activity", .db="activity_db", ...})
```

Use separate steps **only** when a later query depends on a value the earlier one produced.

---

### Rule 4 — SQL `{{values}}` are prepared-statement parameters

Auto-bound, never spliced. SQL injection impossible. Don't pre-quote, don't pre-escape.

```c
✅ query({.db="db", .query="insert into todos(title) values({{title}});"})
❌ query({.db="db", .query="insert into todos(title) values('{{title}}');"})  // double-quoted
```

For transactions: `BEGIN`/`COMMIT`/`ROLLBACK` directly in queries.

---

### Rule 5 — `query()`/`find()` item: asset name OR `.query`. Pick one. The asset must exist.

```c
✅ query({.set_key="todos", .db="todos_db", .query="select ..."})  // inline; works anywhere

✅ query({"get_todos", .set_key="todos", .db="todos_db"})  // asset by name
   // requires: .context = {{"get_todos", (asset){#embed "get_todos.sql"}}}
   // WITHOUT that .context entry, this is a phantom reference — fails.

❌ query({"get_todos", .set_key="todos", .db="todos_db", .query="..."})  // both → boot rejection

❌ query({"get_todos", .set_key="todos", .db="todos_db"})  // when no .context defines "get_todos"
```

**If your snippet has no `.context` block embedding SQL files, use inline `.query` only.** Don't reach for the positional name to avoid writing the SQL — that produces a phantom reference. The asset-name form is for when SQL grows large and you've extracted it; not for casual use.

Same rule applies to `find()` and `render()` (asset name in `.context` vs `.template` inline).

---

### Rule 6 — `find()` raises `http_not_found` on zero rows; `query()` does not

Otherwise identical. `find()` for "must exist" lookups (detail pages, by-id reads). `query()` for lists, counts, writes, anywhere zero rows is normal.

---

### Rule 7 — No `malloc`/`free`, no threads, no mutexes

Per-request arena handles memory. Reactors + thread pool handle concurrency. App code never calls these.

For a buffer: `char *buf = allocate(256);` (reclaimed at request end). For external-lib pointer cleanup: `defer_free(out);`.

---

### Rule 8 — Resource-based, not route-based

Resources referenced by **name**, never hard-coded path:

```c
{{url:todos}}           // → /todos
{{url:todo:5}}          // → /todos/5  (literal arg)
{{url:todo:id}}         // → /todos/{id from context}
redirect("todo:{{id}}") // 302 to /todos/{id}
reroute("todos")        // re-enter pipeline server-side
```

---

## C SYNTAX PATTERNS — required for compilation

Four patterns trip up small models even when MACH semantics are correct.

### Pattern 1 — Adjacent string literals concatenate. ONE quoted line per source line.

C joins adjacent strings at compile time. Use this for every multi-line SQL and every inline template. Never put a raw newline inside a single quoted string. Never mix quoted and bare text on one line.

```c
✅ "CREATE TABLE projects ("           // each line its own
   "id INTEGER PRIMARY KEY,"            // properly terminated string
   "name TEXT NOT NULL"                 // C concatenates them
   ");"

❌ "CREATE TABLE projects (              // raw newline = compile error
     id INTEGER PRIMARY KEY, ...

❌ "<ul>"
     {{#tasks}}<li>{{title}}</li>{{/tasks}}    // bare Mustache, not in string
   "</ul>"
```

A MACH inline template is **not a heredoc** — it's a stack of small C string literals the compiler glues. Every fragment, every section marker, every HTML scrap must be inside its own `"..."`.

### Pattern 2 — Any `"` inside a C string ends it. Use `'` for HTML, no quotes for SQL identifiers.

#### 2a — SQL identifiers: don't quote them
```c
✅ "CREATE TABLE projects (id INTEGER PRIMARY KEY, name TEXT NOT NULL);"
❌ "CREATE TABLE projects ("id" INTEGER ..., "name" TEXT ...);"  // " ends C string
```
SQLite/Postgres/MySQL all accept unquoted identifiers for normal names. Never quote in MACH SQL unless reserved word (then escape with `\"`).

#### 2b — HTML attributes: USE SINGLE QUOTES EXCLUSIVELY. Never `\"`.

```c
✅ "<li class='task' data-id='{{id}}'>{{title}}</li>"   // single quotes — nothing to escape

⚠️ "<li class=\"task\" data-id=\"{{id}}\">{{title}}</li>"
   // works, but every \" is a slip waiting to happen.
   // Drop one backslash on one attribute → compile error.

❌ "<li class=\"task\" data-id="{{id}}">{{title}}</li>"
   //                            ↑ bare " — ends C string. The most-recurring HTML failure
   //   is mixing escaped \" and bare " in one template. Don't escape; use ' everywhere.
```

**Rule:** if your inline template contains any `\"`, you took the harder route. Switch every HTML attribute to `'...'` before emitting.

### Pattern 3 — All `.fields` go INSIDE one `(config){...}` block. Brace tracking is the most-regressed bug.

There is **no file-scope config in MACH.** `.databases`, `.modules`, `.resources` are NOT standalone declarations — they are fields of the single struct value `mach()` returns. Designated-initializer syntax (`.field = value`) is meaningful only **inside** a struct initializer.

> **Mechanical rule:** in the entire `mach()` body there must be **exactly one `};`** (closing `(config){...}` + return) and **exactly one `}`** after it (closing the function). No others.

#### Three failure modes (all close `(config){...}` at the wrong point)

```c
✅ config mach(){
     return (config){          // depth 1 opens here
       .resources = {...},     // ,  separator
       .databases = {{...}},   // ,  separator
       .modules   = {sqlite}   // last field, no comma
     };                        // ONE };  closes (config){...} + return
   }                           // ONE }   closes function

❌ A: premature `};` mid-function
   .resources = {...}
   };                          // ← ends return early
   .databases = {...};         // ← orphan inside function body
   .modules = {sqlite};

❌ B: fields placed AFTER mach() closes (file scope)
   };
   }                           // function ends here
   .databases = {...};         // ← floating at file scope = compile error
   .modules = {sqlite}
   // Giveaway: comment near here saying "global config" or "module-level" — there's no such thing.

❌ C: `},` closes (config){...} too early mid-function (most-recurring)
   .resources = {...
     }
   },                          // ← `},` = `}` closed (config){...} + stray `,`
     .databases = {{...}},     // ← orphan in function body
     .modules = {sqlite}
   };                          // orphan close
```

#### Post-field-block boundary check

After every `.field = ...` block closes with `}`, the next non-whitespace token must be:
- `,` → another `.field = ...` follows (still inside `(config){...}`). ✅
- `};` → this was the last field, end of return. ✅
- `},` → BUG: extra `}` closed `(config){...}` early plus stray `,`. **Failure mode C.** Delete one `}`.

**Trouble signals (any of these = bug):**

| You see | What broke |
|---|---|
| Two `};` lines in `mach()` | Failure mode A |
| `};` `}` then `.field =` lines below | Failure mode B (file-scope orphans) |
| `},` mid-function with `.field =` lines below | Failure mode C |
| `.engine = sqlite_db` but no `.modules = {sqlite}` | Missing bundled module (see Modules) |
| Indentation says fields are inside `(config){...}` but braces say otherwise | Trust braces, not indent |

### Pattern 4 — Pipeline step parens: every `step(` needs a matching `)` before the next step's `,`

Each pipeline step is a C function call. `validate(...)`, `query(...)`, `join(...)`, `render(...)`, `redirect(...)`, `emit(...)`, `task(...)`, etc. — every one opens with `(` and must close with `)` before the next step's `,`.

The slip-prone case is **`render(...)` with a long inline template**. By the time you finish the concatenated string literal, it's easy to lose track of the outer `render(` you opened many lines ago.

```c
✅ render(.template =
     "{{#project}}"
       "<h1>{{name}}</h1>"
       "<p>{{id}}</p>"
     "{{/project}}")          // ← `)` closes render( before the next step or `}`

❌ render(.template =
     "{{#project}}"
       "<h1>{{name}}</h1>"
       "<p>{{id}}</p>"
     "{{/project}}"            // ← string ends fine, but no `)` to close render(
   }                            // ← this `}` gets eaten by the unclosed render(
                                //   parser error, will not compile
```

**Mechanical rule:** after every `step(`, count opening `(` and matching `)` characters in the step's body. Before the next `,` (separating from the next step) or `}` (closing the pipeline), the count must balance back to zero. The closing `)` of an outer step belongs **at the end of that step's content, before the comma**.

**Especially watch:**
- `render(.template = "..." "..." "...")` — closing `)` after the last string fragment, before any `}`
- `query({...}, {...})` — closing `)` after the last `{...}` item
- `validate({...}, {...})` — same shape as `query()`
- `join(.target_table_key=..., ...)` — closing `)` after the last named field
- Nested calls like `nest({step(...), step(...)}, .if_context="x")` — outer `)` after the conditional

**Trouble signal:** in any pipeline, if the last step before `}` (closing the pipeline block) ends without a `)` matching the step's `(`, the whole pipeline is malformed.

### Self-check before emitting any snippet

1. **Strings:** every line of every multi-line SQL and template starts with `"` and ends with `"`. No raw newlines or bare HTML/SQL between strings.
2. **Bare `"`:** no SQL identifiers in `"..."`. No HTML attributes in `attr="..."` — use `'...'` or `\"...\"`. **Shortcut: any `\"` in inline template → switch whole template to single quotes; faster than auditing.**
3. **Brace count:** exactly one `};` (closes `(config){...}` + return) and one `}` (closes function). All `.fields` inside that one initializer, comma-separated.
4. **No file-scope fields:** scan from closing `}` of `mach()` to end of file. Nothing between except other `config` functions or `#include`. If you see `.databases`/`.modules`/`.resources`/etc. floating, move them inside.
5. **Modules registered:** every `.engine = X_db` requires `X` in `.modules`. Search snippet for `.modules` — zero matches = bug.
6. **Step parens balanced:** every `step(` (validate, query, join, render, etc.) has a matching `)` before the next `,` or before the pipeline-closing `}`. Especially check the last step in each pipeline — easy to drop the `)` after a long template body.

---

## CANONICAL WORKED SNIPPET — copy this shape for parent + children pipelines

This is the right shape for: project+tasks, blog+comments, order+line_items, user+sessions, playlist+tracks, anything with a parent-child relation. **Substitute names freely; do not change shape.**

```c
#include <mach.h>
#include <sqlite.h>

config mach(){
  return (config){             // ← (config){ opens — depth 1
    .resources = {             //   .resources opens — depth 2
      {"project", "/projects/:id",
        .get = {                   // ← REQUIRED named field. Verb pipelines have NO
                                    //   positional form — never put the pipeline
                                    //   directly in {...} after the URL (that slot
                                    //   is .steps middleware, not .get).
          validate({"id", .validation = validate_integer,
            .message = "must be an integer"}),

          // Rule 3: ONE step, TWO items, SAME db (Rule 2: parent + child = one domain)
          query(
            {.set_key="project", .db="projects_db",
             .query="select id, name from projects where id = {{id}};"},
            {.set_key="tasks",   .db="projects_db",   // ← SAME db
             .query="select id, project_id, title from tasks where project_id = {{id}};"}
          ),

          join(.target_table_key="project", .target_field_key="id",
               .nested_table_key="tasks", .nested_field_key="project_id",
               .target_join_field_key="tasks"),

          // Rule 1 Pattern C: enter {{#project}} for ALL parent fields,
          // including its own scalars (name, id) and nested children (tasks).
          render(.template =
            "{{#project}}"
              "<h1>{{name}}</h1>"
              "<p>Project ID: {{id}}</p>"
              "<ul class='tasks'>"
                "{{#tasks}}<li class='task'>{{title}}</li>{{/tasks}}"
              "</ul>"
            "{{/project}}")        // ← `)` closes render( — REQUIRED.
                                    //   Easy to drop after a long template.
                                    //   See C Syntax Pattern 4.
        }
      }
    },                         // ← close .resources (depth 2 → 1), comma to continue
                               //   ⚠️ depth IS 1 here. NEXT line must be another
                               //   `.field =` OR `};`. Writing `},` here = Failure mode C.

    // Rule 2: ONE db, TWO migrations
    .databases = {{
      .engine     = sqlite_db,
      .name       = "projects_db",
      .connect    = "file:projects.db?mode=rwc",
      .migrations = {
        "CREATE TABLE projects (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL);",
        "CREATE TABLE tasks ("
          "id INTEGER PRIMARY KEY AUTOINCREMENT,"
          "project_id INTEGER NOT NULL REFERENCES projects(id),"
          "title TEXT NOT NULL"
        ");"
      }
    }},                        // ← close .databases (depth 2 → 1), comma to continue

    .modules = {sqlite}        // ← REQUIRED. `.engine = sqlite_db` above forces this.
                               //   Every .engine = X_db needs X in .modules.
                               //   Never omit "for brevity" — there is no elsewhere.
  };                           // ← `};` closes (config){...} + return (depth 1 → 0).
                               //   This MUST be the only `};` in the function.
}                              // ← `}` closes function body.
```

**What the shape requires (all immutable regardless of names):**
- ONE `.databases` entry containing migrations for parent AND child
- ONE `query()` step with multiple items, all SAME `.db`
- ONE `join()` between them
- Template wraps everything in `{{#parent}}...{{/parent}}`, children iterated inside
- `.modules = {<engine>}` listed once
- Everything inside ONE `(config){...}` block, ONE `};`, ONE `}`

---

## MODULES — two different things called "module"

> **1. User-defined modules** = `config foo(){...}` functions you write to split an app into features. **Skip these for small/single-file snippets** — put everything in `config mach()`. Defining one without registering under `.modules = {foo, ...}` makes it dead code.
>
> **2. Bundled modules** = engine and feature modules shipped with MACH. **MUST be registered in `.modules` whenever you use what they provide.** `.modules` is never optional.

#### Module-registration trigger rule (mechanical)

Every `.engine = X_db` line requires `X` in `.modules`:

| `.engine =` | `.modules` must include |
|---|---|
| `sqlite_db`   | `sqlite`   |
| `postgres_db` | `postgres` |
| `mysql_db`    | `mysql`    |
| `redis_db`    | `redis`    |
| `duckdb_db`   | `duckdb`   |

Feature modules:

| You use | Add to `.modules` |
|---|---|
| `ds_sse(...)` | `datastar` |
| `session()`, `logged_in()`, `login()`, `signup()` | `session_auth` |
| `is_htmx` flag, HTMX-aware rendering | `htmx` |

**Pre-emit check:** search your output for the literal string `.modules`. Zero matches = bug. If `.modules` exists but missing an entry for an engine you used = bug. Apply at point of typing — memory-level reminders don't reliably fire mid-generation.

---

## REFERENCE

### Notation

`{}` = single value/struct. `{{}}` = array of structs. `query({...}, {...})` = multiple items in one step.

### Context

Per-request key-value store. Three scopes:
- `input:xxx` — raw request params
- `error:xxx` — validation/error data
- (unprefixed) — app scope: query results, validated inputs, `.context` values

`validate()` promotes `input:` → app scope on success. `.context` seeds variables and assets at root, baked at compile time via `(asset){#embed "file"}`.

```c
.context = {
  {"site_name", "MACH App"},
  {"layout",    (asset){#embed "static/layout.mustache.html"}},
  {"get_todos", (asset){#embed "todos/get_todos.sql"}}
}
```

### Databases

Migrations forward-only, index-based, applied once each in array order, tracked in `mach_meta`. Seeds idempotent. Multi-tenant via `{{interpolation}}` in `.connect`; connections pooled with LRU.

**Engines:** `sqlite_db`, `postgres_db`, `mysql_db`, `redis_db`, `duckdb_db`

```c
.databases = {{
  .engine = sqlite_db, .name = "blog_db",
  .connect = "file:{{user_id}}_blog.db?mode=rwc",   // multi-tenant
  .migrations = {"CREATE TABLE blogs (...);", "CREATE TABLE comments (...);"},
  .seeds = {"INSERT OR IGNORE INTO blogs(...) VALUES(...);"}
}}
```

### Resource Pipelines

Each `.resources` entry is a named URL endpoint. Identified by name in `{{url:name}}`, `redirect()`, `reroute()` with colon-separated args (`name:arg1:arg2`).

URL helpers: `{{url:todos}}`, `{{url:todo:5}}` (literal), `{{url:todo:id}}` (context), `{{url:org_todo:acme:5}}` (multi-arg).

Path specificity automatic: `/todos/active` beats `/todos/:id`. Verb selection: HTTP method, or `?http_method=...` (lets HTML forms reach PATCH/DELETE/SSE).

**Fields:**
- `.name` *(pos)*, `.url` *(pos)*, `.steps` *(pos)* — `.steps` is **middleware only**, runs before every verb
- `.mime` — default response content type
- `.get`, `.post`, `.put`, `.patch`, `.delete` — verb pipelines (**MUST be named fields, never positional**)
- `.sse` — persistent SSE channel; first positional is channel name
- `.errors` — terminal handlers keyed by error code
- `.repairs` — resumable handlers keyed by error code

> **The third positional slot (`{...}` after the URL) is `.steps` middleware ONLY.** Do NOT put the GET/POST pipeline there expecting it to be inferred — verb pipelines have no positional form. They MUST use the named `.get =`, `.post =`, etc. fields. A resource with steps in the third slot but no `.get =` field has no GET handler and returns 404/405.
>
> ```c
> ❌ {"project", "/projects/:id",
>      {validate(...), query(...), join(...), render(...)}    // ← interpreted as
>    }                                                          //   .steps middleware,
>                                                                //   no GET handler!
>
> ✅ {"project", "/projects/:id",
>      .get = { validate(...), query(...), join(...), render(...) }   // ← named field
>    }
>
> ✅ {"project", "/projects/:id",
>      {session(), logged_in()},        // ← .steps middleware (small middleware steps)
>      .get   = { ... },                // ← still need the named verb field
>      .post  = { ... }
>    }
> ```
>
> If your resource has only one verb (typical), use the named field directly and skip the `.steps` slot entirely — see the canonical worked snippet.

```c
{"todo", "/todos/:id", {validate({"id", .validation="^\\d+$"})},   // ← {...} = .steps middleware
  .mime  = mime_html,
  .get   = { find({"get_todo", .set_key="todo", .db="todos_db"}), render("todo") },   // ← named .get
  .patch = { validate({"title", .validation=validate_not_empty}),
             query({.db="todos_db", .query="update todos set title={{title}} where id={{id}};"}),
             redirect("todo:{{id}}") },
  .delete = { query({.db="todos_db", .query="delete from todos where id={{id}};"}),
              redirect("todos") },
  .sse    = {"todo/{{id}}", sse(.event="ready")},
  .errors = {{http_not_found, {render("404")}}}
}
```

**MIME:** `mime_html`, `mime_txt`, `mime_sse`, `mime_json`, `mime_js`

### Template Helpers

`{{helper:args}}` — colon-separated, never dot.

| Helper | Purpose |
|---|---|
| `{{raw:field}}` | unescaped output (default escapes) |
| `{{precision:field:N}}` | numeric format, N decimals |
| `{{input:field}}` | raw request param (form repop) |
| `{{error:field}}` | truthy when field has error (use as section) |
| `{{error_message:field}}`, `{{error_code:field}}` | error message / status code |
| `{{url:name[:args]}}` | resource URL with positional args |
| `{{asset:filename}}` | cache-busted URL for `public/` file |
| `{{csrf:token}}`, `{{csrf:input}}` | CSRF token / hidden input (auto-verified) |

> **The table is exhaustive. Helpers not in it do not exist.** Other Mustache implementations have `{{length}}`, `{{count}}`, `{{size}}`, `{{first}}`, `{{last}}`, `{{index}}`, `{{#if}}`, `{{#each}}`, `{{else}}`, lambdas, partials. **None work in MACH.**
>
> **Supported template features:** field interpolation, `{{#name}}` (truthy/iteration), `{{^name}}` (falsy/empty), helpers above. HTML comments `<!--...-->` work; Mustache comments `{{!...}}` do NOT — use HTML.
>
> **Doing common things you might reach for missing helpers:**
> - **Counts:** compute in SQL. `{.set_key="stats", .query="select count(*) as n from tasks where project_id = {{id}};"}` then `{{#stats}}{{n}} tasks{{/stats}}`.
> - **Conditionals:** `{{#has_x}}...{{/has_x}}` where `has_x` is set by query/`exec()`. There is no `{{#if x}}`.
> - **First/last:** different SQL — `limit 1`, `order by ... desc limit 1`.
> - **Index in iteration:** `select row_number() over (...) as n` then `{{n}}`.
>
> **The template layer is a renderer, not a programming language.** If you need a feature not listed, do it in SQL or `exec()`, then render the result.

### Pipeline Steps

Every step accepts `.if_context` and `.unless_context`.

#### validate

Regex-checks request params. On success, promotes `input:name` → app scope. On failure, sets `error:name`, raises `http_bad_request`. All validations in one call complete before the error fires.

`.param_key` *(pos)*, `.validation` (regex/macro), `.message`, `.optional`, `.fallback`.

```c
validate(
  {"email",  .validation=validate_email,     .message="must be email"},
  {"title",  .validation=validate_not_empty, .message="cannot be empty"},
  {"page",   .fallback="1", .validation="^\\d+$"},
  {"filter", .optional=true, .validation="^(active|done)$"}
)
```

**Built-ins:** `validate_not_empty`, `validate_alpha`, `validate_alphanumeric`, `validate_slug`, `validate_no_html`, `validate_integer`, `validate_positive`, `validate_float`, `validate_percentage`, `validate_email`, `validate_uuid`, `validate_username`, `validate_date`, `validate_time`, `validate_datetime`, `validate_url`, `validate_ipv4`, `validate_hex_color`, `validate_zipcode_us`, `validate_phone_e164`, `validate_cron`, `validate_no_sqli`, `validate_token`, `validate_base64`, `validate_boolean`, `validate_yes_no`, `validate_on_off`. Define your own: `#define validate_zipcode "^\\d{5}$"`.

#### find & query

Both run DB queries. `find()` raises `http_not_found` on zero rows; `query()` does not. Otherwise identical.

`.set_key` stores result as TABLE in context (always). SQL inlined with `.query` OR loaded by name from `.context` as positional (Rule 5 — asset must exist). Multiple items in one step run **concurrently** (Rule 3), even across dbs. `{{values}}` parameter-bound (Rule 4). Transactions: `BEGIN`/`COMMIT`/`ROLLBACK`.

`.template_key` *(pos)*, `.query`, `.set_key`, `.db`, `.if_context`/`.unless_context` *(per item)*.

```c
query(
  {"get_todos", .set_key="todos", .db="todos_db"},
  {.set_key="count", .db="todos_db", .query="select count(*) as n from todos where user_id={{user_id}};"},
  {.if_context="show_urgent", .set_key="urgent", .db="todos_db",
   .query="select id, title from todos where priority='high';"}
)
```

#### join

Nests records from one context table into matching records of another, in memory. After `join()`, inner records live INSIDE outer records. Templates must enter outer section.

`.target_table_key`, `.target_field_key`, `.nested_table_key`, `.nested_field_key`, `.target_join_field_key` — see canonical snippet.

#### fetch

HTTP request → context. JSON parsed into tables/records; text stored as string. Multiple items run concurrently.

`.url` *(pos)*, `.set_key`, `.method` (default `http_get`), `.headers` (array of `{name, value}`), `.json`/`.text` (context key as body).

```c
fetch("https://api.x.dev/charge",
  .set_key = "receipt", .method = http_post,
  .headers = {{"Authorization", "Bearer {{api_key}}"}, {"Idempotency-Key", "{{order_id}}"}},
  .json = "order")
```

**Methods:** `http_get`, `http_post`, `http_put`, `http_patch`, `http_delete`, `http_sse_method`

#### exec

Calls C function/block with imperative context access. Dispatched to thread pool. Use for blocking I/O or CPU work. Trigger error pipeline via `error_set()`.

```c
exec(^(){ auto t = get("challengers"); record_set(table_get(t,0), "x", record_get(table_get(t,1), "id")); })
exec(.call = assign_opponents)
```

**Imperative API:** `get/set/has/format`, `allocate/defer_free`, `error_set/get/has`, `table_new/count/get/add/remove/remove_at`, `record_new/set/get/remove`.

#### emit / task

```c
emit("todo_created")    // pub/sub event
task("recount_todos")   // enqueue async job
```

#### sse / ds_sse

`sse(.channel="todos/{{user_id}}", .event="updated", .data={"id: {{id}}"})` — broadcasts on channel; without channel, sends only to requester.

`ds_sse(...)` — Datastar SSE (DOM updates + reactive state). Requires `.modules = {datastar}`. Fields: `.channel`, `.target`, `.mode` (`mode_outer`/`inner`/`replace`/`prepend`/`append`/`before`/`after`/`remove`), `.elements`, `.signals` (JSON), `.js`.

#### render

Outputs Mustache template. Auto-escapes (use `{{raw:field}}` to opt out). All field access follows Rule 1 — sections, never dot. Run Template Checklist on every `{{...}}` before emitting.

`.template_key` *(pos)*, `.template`, `.status`, `.mime`, `.engine` (`mustache` default, `mdm` for Markdown-with-Mustache), `.json_table_key` (serialize table as JSON).

```c
render("todos")
render(.template = "<h1>{{site_name}}</h1>")
render("not_found", .status = http_not_found)
render(.json_table_key = "todos")
```

**Statuses:** `http_ok` (200), `http_created` (201), `http_redirect` (302), `http_bad_request` (400), `http_not_authorized` (401), `http_not_found` (404), `http_error` (500).

> Use either positional asset name (must exist in `.context`) OR inline `.template`. Don't reference phantom asset names.

#### headers / cookies / redirect / reroute / nest

```c
headers({{"X-Request-Id", "{{request_id}}"}, {"Cache-Control", "no-store"}})
cookies({{"session", "{{session_id}}"}})

redirect("todos")              // 302 /todos
redirect("todo:{{id}}")        // 302 /todos/{id}
reroute("todo:{{id}}")         // server-side, in-process

nest({query({...}), render("urgent")}, .if_context="is_urgent")  // shared conditional
```

### Conditionals

Every step accepts `.if_context` (run when key present) / `.unless_context` (when absent). Works on validated inputs, query results, framework flags (`is_htmx`), or flags set by `exec()`.

```c
render("fragment",  .if_context="is_htmx")
render("full_page", .unless_context="is_htmx")
```

### Errors and Repairs

On failure, MACH searches handlers bottom-up: resource → module → root.
- **Errors** terminal: send response, end request.
- **Repairs** resumable: fix context, resume original pipeline at step after failure.

If no matching repair, falls through to errors. Error scope shared across `validate()` and `error_set()`: `{{error:name}}`, `{{error_code:name}}`, `{{error_message:name}}`. Raw input remains in `input:name`.

```c
.errors = {
  {http_not_found,    {render("404")}},
  {http_bad_request,  {render("form")}},
  {http_error,        {render("500")}}
},
.repairs = {{http_not_authorized, {exec(.call = refresh_session_token)}}}
```

**Codes:** built-ins above; any int works. `#define err_quota_exceeded 723` for domain-specific.

### Events (cross-module pub/sub)

When `.publishes` exists anywhere, MACH creates `mach_events` to track delivery. Crashes don't drop events; replay on next boot.

```c
// publisher
.publishes = {{"todo_created", .with = {"user_id", "title"}}},
.resources = {{"todos", "/todos", .post = {validate(...), query({"insert_todo", .db="todos_db"}),
                                            emit("todo_created"), redirect("todos")}}}

// subscriber (different module, OWN db per Rule 2)
.events = {{"todo_created", {query({.db="activity_db",
  .query="insert into activities(kind, user_id) values('created', {{user_id}});"})}}}
```

### Tasks

Async pipelines on task reactors. Triggered by `task("name")` or `.cron`. Durable: `mach_tasks` checkpoints context after each step; crash mid-task resumes at failed step.

```c
.tasks = {
  {"recount_todos",
    {query({.db="todos_db", .query="update users set todo_count = ... where id = {{user_id}};"})},
    .accepts = {"user_id"}},
  {"daily_digest",
    {query({...}), emit("digest_ready")},
    .cron = "0 8 * * *"}
}
```

### Modules & Composition

Every app/module returns `config`. Root `main.c` defines `mach()`; modules define functions with any name. Module owns its resources, **its own db** (one per domain), migrations, templates, event contracts. Same-name conflicts: root wins. Modules communicate ONLY via pub/sub events.

`.name` — module identifier. `.modules` — modules to compose.

A module file:
```c
config blogs(){
  return (config){
    .name = "blogs",
    .resources = {{"blog", "/blogs/:id", .get = {/* validate→query→join→render */}}},
    .databases = {{
      .engine = sqlite_db, .name = "blog_db",
      .connect = "file:blogs.db?mode=rwc",
      .migrations = {
        "CREATE TABLE blogs (...);",
        "CREATE TABLE comments (... REFERENCES blogs(id) ...);"
      }
    }}
  };
}
```

Bring in from `main.c`:
```c
#include "blogs/blogs.c"
config mach(){ return (config){ .modules = {blogs, sqlite} }; }
```

**Bundled modules (add to `.modules`):** `sqlite`, `postgres`, `mysql`, `redis`, `duckdb`, `htmx`, `datastar`, `tailwind`, `session_auth`.

**`session_auth` provides:** `session()` (attaches session, sets `user_id`), `logged_in()` (guard, raises `http_not_authorized`), `login()`, `logout()`, `signup()`. Common as resource middleware:
```c
{"dashboard", "/dashboard", {session(), logged_in()}, .get = {render("dashboard")}}
```

### Static Files / External Deps

`public/` files served directly. Reference with `{{asset:filename}}` (content-checksummed URL, immutable cache).

External C libs: drop into `/vendor` (auto-discovered/linked), or use custom Dockerfile (`FROM mach:latest`, `apt-get install`).

Memory bridges: `allocate(N)` (per-request arena), `defer_free(ptr)` (cleanup at request end).

### Architecture (brief)

- **Boot once:** `mach()` runs at boot; config compiled into execution graph.
- **Multi-reactor:** request reactors (one/CPU), task reactors (one/CPU), shared thread pool for `exec()` and blocking I/O.
- **Memory:** per-request arena allocators; cleared at request end. Pipelines >5MB abort with 500.
- **Safety:** SQL injection prevented by parameter binding (Rule 4). XSS prevented by `render()` auto-escape. CSRF prevented by `{{csrf:token}}`/`{{csrf:input}}`.

---

## PRE-EMIT SCAN — search your output for these strings before returning

| Search for | Failure |
|---|---|
| `.` between `{{` and `}}` (e.g. `{{x.y}}`) | Rule 1: dot notation |
| Two `_db",` lines with different prefixes for ONE domain (e.g. `projects_db` + `tasks_db`) | Rule 2: parent+child split |
| Multiple `query({` calls in one pipeline that don't depend on each other | Rule 3: serial when concurrent needed |
| Positional asset name in `query()`/`find()` with no matching `.context` entry | Rule 5: phantom asset |
| `config X()` not appearing in any `.modules = {...}` | Unregistered user module (dead code) |
| `.engine = X_db` with no `X` in `.modules` | Missing bundled module (most-recurring regression) |
| `{{#child}}` at root scope after a `join(child→parent)` | Pattern C: orphan section |
| Bare `{{name}}` at root when `name` came from `set_key="X"` table | Pattern C: missing `{{#X}}` wrapper |
| `\"` in inline template | Pattern 2b: switch whole template to `'...'` |
| `{{length}}`, `{{count}}`, `{{#if}}`, `{{#each}}`, etc. | Improvised helpers — not in MACH |
| `{{#a}}` opened twice in same scope | Overlapping sections (Check 4) |
| `{{/x}` (one `}`), `{x}}`, `{{{x}}}`, `{ {x} }` | Malformed tag delimiters (Check 0) |
| Two `};` in one `mach()` | Pattern 3 Failure A |
| `};` then `}` then `.field =` lines | Pattern 3 Failure B (file-scope orphans) |
| `},` between fields where `}` closed `(config){...}` | Pattern 3 Failure C |
| `{{/x}}` with no matching `{{#x}}` earlier | Section balance (Check 4) |
| `validate()` step missing when prompt asked for one | Prompt-following: re-read prompt |
| Resource entry with `{...}` after URL containing the pipeline, but no `.get =` / `.post =` / etc. named field | Verb pipeline placed in `.steps` middleware slot — resource has no GET handler, returns 404. Use `.get = {...}` named field. |
| Last step in a pipeline ends without `)` matching its opening `(` (especially `render(.template = "..." "..."` without closing `)`) | Pattern 4: unclosed step paren. The next `}` gets eaten by the unclosed call. Add the missing `)`. |

If any match: stop and fix. When in doubt about parent + child: copy the **canonical worked snippet** above and rename.