AILang/docs/PROSE_ROUNDTRIP.md

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.