Trace a worked example

Scenario: An invoice extractor returns {invoice_id, currency, total_cents, due_date, confidence}. The schema requires integer cents and ISO dates; a business rule checks that line-item cents sum to total_cents before any payment workflow sees it.

Write the trace as numbered state transitions, not a polished story:

1. Capture the input, version, identity, and assumptions.
2. Apply the mechanism: The application defines allowed fields, types, enums, required properties, and whether extra properties are forbidden. Some providers constrain token decoding to valid schema paths; others offer JSON mode that guarantees only parseable JSON. The application still parses, validates, applies business rules, and handles refusal or truncation.
3. Record the relevant controls: schema strictness; required versus optional fields; enums; numeric bounds; nullable fields; additionalProperties; schema version; retry policy; validation errors; and separation between extraction and action.
4. Calculate or inspect the intermediate signal: if 970 of 1,000 outputs parse and 930 pass the schema, parse rate = 97% but end-to-end schema-valid rate = 93%; report both.
5. Compare the result with a baseline and an acceptance threshold.
6. Store enough evidence to reproduce the decision without storing unnecessary sensitive content.

Now perturb the trace. Change one input to a long, stale, ambiguous, or unauthorized case. A robust design should either continue within its contract or abstain visibly. Silent degradation is worse than a clear refusal because downstream systems may interpret fluent output as verified output.

An invoice extractor returns {invoice_id, currency, total_cents, due_date, confidence}. The schema requires integer cents and ISO dates; a business rule checks that line-item cents sum to total_cents before any payment workflow sees it.

The worked number is if 970 of 1,000 outputs parse and 930 pass the schema, parse rate = 97% but end-to-end schema-valid rate = 93%; report both. State the unit and denominator whenever you report it. A percentage without a denominator can conceal a tiny sample; a latency without a percentile can conceal slow users; a similarity score without a labeled task can conceal irrelevant neighbors. Compare the observed value with a threshold chosen before seeing the final test result.

Now test the tempting shortcut. Suppose the team optimizes only the most visible metric. The result may look better while the system becomes less trustworthy. The reason is concrete: Strict schemas simplify downstream code but can make partial answers harder. Large nested schemas consume tokens and reduce model reliability. Retries can repair transient failures but may duplicate side effects unless generation and execution are separate. This is why the decision record must include both the intended gain and the tolerated regression. If the tolerated regression is unknown, the change is not ready for a consequential workflow.

• Prefer a measured baseline over a persuasive demo.
• Keep versions, inputs, and thresholds reproducible.
• Separate syntactic success from semantic correctness and authorization.
• Escalate or abstain when evidence falls outside the contract.
• Re-evaluate when data, traffic, models, providers, or user goals change.

These rules turn the topic into an engineering decision rather than a slogan. They also make disagreement productive: another person can challenge the assumptions, rerun the evaluation, and reach a documented conclusion.

The trace used one set of assumptions. Change one quantity by a realistic amount while holding the others fixed, then recompute the result. Next change a categorical assumption: model version, tenant, language, traffic shape, data freshness, or permission level. Mark which steps remain valid and which must be repeated. This is a stronger test than narrating the happy path because it reveals hidden coupling. Preserve the original and perturbed traces side by side, including intermediate values, so a reviewer can locate the first point at which their behavior diverges.