Contracts — เขียนสถานะและสัญญาให้ตรวจได้Make the Workflow a Typed State Machine

1. The engineering problem

A boolean named safe hides too much. Was the request malformed, unauthorized, ambiguous, or correct but poorly explained? Those failures need different responses. Represent a stage result as Gate(state, reason), with pass, reject, review and revise as explicit intermediate states. The overall workflow returns accepted_draft, reject or review. A revision is an internal transition with a finite budget, not a promise that the user will eventually get a passing answer.

Define ownership for each transition. Input validation may reject malformed data. Authorization may reject an unavailable action. Semantic uncertainty goes to review. A behavior mismatch may request a revision. An accepted candidate still ends at a human review boundary. In the companion a rejected or reviewed run has draft=None; this makes it harder for a careless UI to display an unapproved artifact as an accepted result. The trace carries stage names and reason codes so a caller does not have to parse English error messages.

2. The boundary to design

The normal sequence is input → policy → decision response validation → semantic input check → context → generation → output shape → behavior → quality. Policy comes before paid inference because a forbidden action needs no semantic interpretation. Output checks come before interpreting candidate arithmetic. Quality comes after behavior because a persuasive explanation cannot compensate for a wrong function. The fixed sequence is an architectural invariant worth testing whenever someone adds a shortcut or a fallback path.

3. Read the implementation

Implementation excerpt from the companion. Run the complete lesson below with its imports and fixtures.

from workbench.runtime import run, request, FixtureProvider

result = run(request(), FixtureProvider())
print(result["state"])
print([event["stage"] for event in result["trace"]])

A state machine is only as complete as its error paths. Provider errors and expired budgets route to review. Unknown labels do not become a default skill. Missing release evidence does not become success. Draw every exit before implementing the happy path. Our diagram and trace make these edges reviewable; they are a course synthesis, not a new external standard. The useful question in a design review is whether any path can skip a mandatory stage, including retries, caches and human overrides.

4. Compare the outcomes

The following output comes from scripted fixtures that verify architecture behavior. It is not a measurement of live Jev accuracy, latency, or cost.

{
  "state": "accepted_draft",
  "trace": [
    "input",
    "policy",
    "decision",
    "semantic_input",
    "output",
    "behavior",
    "quality"
  ],
  "effects": 0
}

5. Run, break, and explain

Part 03 code · Implementation · Tests: test_accept_still_has_zero_effects · Exercise

git clone https://github.com/Anirach/ai-core-engineering-workbench.git
cd ai-core-engineering-workbench
git checkout 18cdfcd4156d3d02acb8badf3b3a0a823113e0ed
python3 -m workbench.lesson 3
python3 -m unittest tests.test_boundaries.BoundaryTests.test_accept_still_has_zero_effects -v

Your turn

Draw the rejected, reviewed and revised exits for your current AI handler. Check that rejected runs cannot expose an accepted artifact.

Keep three artifacts: the input you tried, the resulting state and reason, and an explanation of which boundary owns that result. Do not change an expected result merely to make a test pass.

6. Sources and limits