# Prose round-trip cycle

## Why

The prose surface (`ail prose`, Iter 20a/20b) is a deliberately
**lossy** projection of a `.ail.json` module: it strips `(con T)`
wrappings, drops redundant parentheses, infixes arithmetic, suppresses
schema rigor that the LLM can re-derive. That makes prose pleasant to
read and edit — but it also means there is no syntactic parser that
turns edited prose back into a `.ail.json`.

Re-integration of free-text edits therefore requires an **LLM
mediator**: a model that understands both the prose intent and the
load-bearing detail in the original `.ail.json`, and emits a new
`.ail.json` that respects both. This document describes the workflow,
the prompt template `ail merge-prose` composes for that mediator, and
the failure modes to watch for.

## The cycle

```
1.  ail prose foo.ail.json > foo.prose.txt
2.  $EDITOR foo.prose.txt                     # human edits freely
3.  ail merge-prose foo.ail.json foo.prose.txt > prompt.txt
4.  cat prompt.txt | <your-llm-cli> > foo.new.ail.json
5.  ail check foo.new.ail.json
6.  mv foo.new.ail.json foo.ail.json          # if check is clean
```

Step 1 is the deterministic projection (Iter 20a/20b).
Step 3 is the prompt composer this iter ships.
Step 4 is the user's external LLM client — Claude Code, the
Anthropic API, OpenAI's CLI, anything that takes a prompt on stdin and
emits text on stdout. AILang ships no client of its own; see *Why no
built-in API client* below.
Steps 5 and 6 reuse existing tooling: `ail check` validates schema +
typechecks, then the user accepts the new module.

## The prompt template

`ail merge-prose <original.ail.json> <edited.prose.txt>` reads both
files and prints the following text to stdout. Nothing more, nothing
less — no fences, no JSON envelope. The shape is exactly what a human
would compose by hand if they wanted to drive the same cycle without
the CLI helper.

```
You are integrating prose edits back into an AILang module.

ROLE
Your job is to produce an updated AILang JSON-AST (.ail.json) that
reflects the human's prose edits while preserving the load-bearing
semantic detail from the original .ail.json.

CONTRACT
The prose is the source of intent: the human edited it to express
what the program should now do. The original .ail.json carries
load-bearing detail that the prose surface elides — preserve those
details unless the prose explicitly contradicts them. Specifically:

  - Mode annotations on fn parameters (`own T`, `borrow T`).
    These are hard contracts (memory model). The prose shows them,
    but if the prose is ambiguous, default to the original.
  - Effect annotations on return types (`with IO`, `with Diverge`).
    Prose shows these too, but again: if uncertain, keep what the
    original had.
  - `tail` flags on calls. The prose prints `tail f(x)`; if the
    edit moved a call, decide whether the new position is still in
    tail position and flag accordingly.
  - Doc strings (`///` lines).
  - Type annotations on signatures and lambdas.
  - Constructor names and arities (the prose `Cons(h, t)` must
    round-trip to a `Term::Ctor` with the right `type` field).

OUTPUT
Output ONLY the new .ail.json bytes. No commentary, no markdown
fences, no preamble or postscript. The output must be valid JSON
parsable by `ail parse` (i.e. by `serde_json` against the
`ailang/v0` schema). The first byte should be `{` and the last
non-whitespace byte should be `}`.

SCHEMA ESSENTIALS
A full reference lives in docs/DESIGN.md ("Data model (MVP)"). The
shape is:

  - Module: { "schema": "ailang/v0", "name": ..., "imports": [...],
    "defs": [...] }
  - Defs are tagged via `kind` ("fn" | "type" | "const").
  - Types are tagged via `k` ("con" | "fn" | "var" | "forall").
  - Terms are tagged via `t` ("lit" | "var" | "app" | "let" | "if"
    | "do" | "ctor" | "match" | "lam" | "seq").
  - Patterns are tagged via `p` ("var" | "lit" | "ctor" | "wild").
  - On `fn-type`: `param_modes` (one of "own"/"borrow" per
    parameter) and `effects` are mandatory. `ret_mode` is mandatory
    when the return type carries a mode.
  - Constructor application uses `Term::Ctor` (`"t": "ctor"`,
    fields `type` + `ctor` + `args`), NOT `Term::App`. The prose
    surface elides the `type` tag (`Cons(h, t)` instead of
    `(term-ctor IntList Cons h t)`) — re-introduce it.
  - Base type names that appear bare in prose (`Int`, `Bool`,
    `Unit`, user types like `IntList`) must be wrapped as
    `{"k": "con", "name": "Int"}` etc. in the JSON.

ORIGINAL .ail.json
<<<ORIGINAL_AIL_JSON
{original_ail_json_here}
ORIGINAL_AIL_JSON

EDITED PROSE
<<<EDITED_PROSE
{edited_prose_here}
EDITED_PROSE

Emit the updated .ail.json now.
```

The two payloads (original JSON, edited prose) are inserted verbatim
between the heredoc-style markers. `merge-prose` does not strip,
re-encode, or otherwise transform either input — both go in
byte-for-byte.

## Failure modes

The mediator is an LLM, so the cycle is intentionally iterative.
Common failure modes and their fix:

  - **Output wrapped in markdown fences (` ```json ... ``` `).** Strip
    the fences (`sed -n '/^{/,/^}/p'`) and re-run `ail check`. If the
    LLM does this consistently, paste a corrective note ("emit raw
    JSON, no fences") at the top of the next prompt.
  - **Output contains commentary before/after the JSON.** Same
    treatment. Most modern LLMs respect "OUTPUT ONLY" but not all.
  - **Invalid JSON / `serde_json` rejects.** Re-run with the parse
    error pasted into the prompt as a corrective note.
  - **Schema-valid but `ail check` fails.** Re-run with the
    diagnostic messages pasted in. Common cases: missing
    `param_modes`, `Term::App` instead of `Term::Ctor`, bare type
    names instead of `{"k":"con","name":"…"}`.
  - **Preserved detail dropped (mode flipped, doc string lost).**
    Re-run with a corrective note naming the missing detail.

The cycle converges in 1–3 rounds for typical edits.

## Why no built-in API client

AILang stays a compiler + tooling. Shipping an HTTP client to one
particular LLM vendor would mean an API key story, rate limiting,
streaming semantics, error mapping, version tracking — all carrying
zero language-level value. The user already has Claude Code, the
Anthropic SDK, the OpenAI CLI, `curl`, or any other client they
prefer; `ail merge-prose` composes the prompt and gets out of the
way. The Unix-pipe shape (`ail merge-prose ... | client | ail check`)
also makes the cycle scriptable without lock-in to one vendor.