# Automatic learned-flow generation

Use this procedure whenever Learn Mode discovers a new user or API flow. Do not stop at a happy-path recording. Convert the evidence-backed state graph into a target-specific flow specification, then automatically generate its synthetic inputs and candidate cases.

## Model the discovered flow

Copy [flow-spec-template.json](flow-spec-template.json) and record:

- stable flow ID, title, kind, intended outcome, actors, preconditions, and cleanup;
- initial, intermediate, terminal, failure, and cancellation states;
- every observed transition with action, source, destination, candidate oracle, guard, side-effect status, and reversibility;
- every discovered input with semantic type, required/nullability signal, exact limits, format, enum, and sensitivity;
- external effects and staleness anchors.

Use observed product terms. Include only states and constraints supported by the current artifact as facts; phrase inferred oracles as candidates. Never place credentials, tokens, cookies, customer data, or real payment data in the specification.

## Generate the flow pack

Run:

```bash
python3 scripts/carbon_learn.py generate-flow \
  --session-dir <session-dir> \
  --spec <flow-spec.json>
```

Use `--replace` only after new evidence changes an existing flow model.

Generation creates:

- concrete safe synthetic values for ordinary, empty/null, type/format, exact boundary, Unicode, emoji, emoticon, RTL, normalization, and encoding cases where applicable;
- synthetic authorized and unauthorized actor references;
- canonical-path, per-transition, forbidden-state, guard, input, authorization, retry/idempotency, interruption/resume, persistence, concurrency/stale-state, and cleanup cases;
- keyboard/accessibility and responsive/history cases for web flows;
- malformed protocol and failure/recovery cases for API flows.

Large boundary values use a deterministic generator description instead of embedding an enormous payload. Materialize the value only at execution time and keep it within the authorized load envelope.

## Preserve the evidence boundary

Generated inputs are fixtures. Generated tests and their oracles are **planned candidates**. Neither is proof that the product supports the inferred behavior or passes the case.

The learning report shows the state graph, generated inputs, and generated cases. `learned-tests.json` contains both promoted supported tests and generated candidate cases in normal CARBON plan shape. A later CARBON run must:

1. confirm target, environment, revision, actor, and staleness anchors;
2. deduplicate against library- and code-derived coverage;
3. prioritize the candidates for the selected Quick, Medium, or Large budget;
4. keep unsafe or unauthorized cases planned;
5. execute selected cases and record actual evidence before assigning pass or fail.

If the graph cannot reach a terminal state, preserve that as an unknown and generate transition coverage without inventing a canonical completion.
