Error Codes

The stato compiler produces three severity levels of diagnostics. Hard errors (E-codes) block writes. Auto-corrections (W-codes) fix common issues silently. Advice (I-codes) suggest improvements.

Hard Errors (E001-E010)

These block the module from being written to disk.

Code	Pass	Message	Cause
E001	1 (Syntax)	Syntax error: `{details}`	Python source has invalid syntax. Fix the syntax error and retry.
E002	2 (Structure)	No class definition found	The file has no Python class. Every stato module must contain exactly one class.
E003	4 (Schema)	Missing required field: `'{field}'`	A required field is missing from the class. Check the module schema for required fields.
E004	4 (Schema)	Missing required method: `'{method}()'`	A required method is missing. Skill modules require `run()`.
E005	6 (Execute)	Runtime execution error: `{error}`	The module raised an exception when executed in the sandbox.
E006	6 (Execute)	Required method `'{method}()'` is not callable	The required method exists but is not callable (e.g., assigned as a string instead of defined as a function).
E007	5 (Type Check)	Field `'{field}'` expects `{expected}`, got `{actual}`	A field has the wrong type and cannot be auto-corrected.
E008	7 (Semantic)	Duplicate step ID: `{id}` / depends_on references nonexistent step	Plan step IDs must be unique, and `depends_on` must reference existing step IDs.
E009	7 (Semantic)	Circular dependency in plan step DAG	The plan steps form a cycle. Reorder dependencies to form a valid DAG.
E010	7 (Semantic)	Invalid status `'{status}'`	Plan step status must be one of: `pending`, `running`, `complete`, `failed`, `blocked`.

Auto-Corrections (W001-W006)

These are fixed automatically. The corrected source is written to disk. The original issue is logged as a warning.

Code	Pass	Message	What It Fixes
W001	5 (Type Check)	`depends_on` is string, auto-wrapping in list	`depends_on = "normalize"` becomes `depends_on = ["normalize"]`
W002	5 (Type Check)	`depends_on` is int, auto-wrapping in list	`depends_on = 1` becomes `depends_on = [1]`
W003	5 (Type Check)	Version missing patch number	`version = "1.0"` becomes `version = "1.0.0"`
W004	7 (Semantic)	Missing status, auto-set to `'pending'`	Plan steps without a `status` field get `status = "pending"`
W005	2 (Structure)	Multiple classes found, using first	If the file contains multiple classes, the first one is used. Others are ignored.
W006	3 (Type Inference)	Cannot confidently infer module type	The class name and fields do not clearly indicate a module type. Defaults to skill. Consider renaming the class (e.g., end with `State` for memory, `Context` for context).

Advice (I001-I006)

These are informational suggestions. They do not block writes or trigger auto-corrections.

Code	Pass	Message	Suggestion
I001	3 (Type Inference)	Class naming convention	Memory modules should end with `State`, context modules with `Context`, protocol modules with `Protocol`.
I002	3 (Type Inference)	No docstring on class	Add a docstring to describe what the module does.
I003	7 (Semantic)	No `lessons_learned` on skill	Skills benefit from a `lessons_learned` field capturing hard-won insights.
I004	7 (Semantic)	No `decision_log` on plan	Plans benefit from a `decision_log` field documenting key architectural choices.
I006	7 (Semantic)	`run()` has no type hints	Adding type hints to `run()` improves readability and tooling support.

Compiler Passes

For reference, the 7 passes in order:

Pass	Name	What It Checks
1	Syntax	`ast.parse` succeeds
2	Structure	Exactly one class found
3	Type Inference	Determine module type from class name, fields, methods
4	Schema Check	Required fields and methods present
5	Type Check	Field types match schema, apply auto-corrections
6	Execute	Run in sandbox, verify methods callable
7	Semantic	Module-specific rules (plan DAG, step statuses, etc.)

Passes run in order. If a pass produces a hard error, subsequent passes may be skipped.

Auto-Correction Mechanics

When the compiler applies auto-corrections (W001-W003), it modifies the source text in-place. To avoid offset drift when multiple corrections target different lines, corrections are applied in reverse line order (highest line number first). The corrected source is stored in ValidationResult.corrected_source and used as input for subsequent passes (Execute and Semantic).

This means a module with both depends_on = "foo" (line 5) and version = "1.0" (line 3) will have both issues fixed in a single validation pass, with the line-5 fix applied before the line-3 fix to preserve character offsets.

Plan Semantic Validation Details

Pass 7 performs module-specific semantic checks. For plan modules, the compiler enforces four constraints:

Step ID uniqueness (E008): every step dict in the steps list must have a unique id value. Duplicates are flagged immediately.
Dependency reference validity (E008): every value in a step’s depends_on list must reference an id that exists in another step. References to nonexistent steps are flagged with the specific step ID and missing dependency.
Status value validation (E010): the status field of each step must be one of five allowed values: pending, running, complete, failed, blocked. If a step has no status field at all, auto-correction W004 sets it to pending.
DAG acyclicity (E009): the compiler builds a directed graph from step dependencies and checks for cycles using DFS with three-color marking (white = unvisited, gray = in current path, black = fully explored). A gray-to-gray edge indicates a cycle, which is reported with the full cycle path.