yoagent-state 0.2.0

Durable state and lineage for long-running agents.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

# yoyo evolve Integration

`yoyo evolve` is the first serious use case for `yoagent-state`.

It needs to grow a project while preserving why each change exists.

## Growth loop

The intended loop is:

```text
record goal
create task
observe project
record snapshot reference
run agent task or eval
observe failure
create hypothesis
propose patch
attach artifacts
apply patch in branch or worktree
run eval
record eval result
decide approve or reject
promote if approved
record lineage
```

```mermaid
flowchart LR
  goal["goal"]
  task["task"]
  snapshot["project snapshot"]
  failure["failure"]
  hypothesis["hypothesis"]
  patch["patch"]
  artifact["diff artifact"]
  eval["eval result"]
  decision["decision"]
  promoted["promoted patch"]

  task -- serves --> goal
  snapshot -- references --> task
  failure -- blocks --> goal
  hypothesis -- explains --> failure
  patch -- addresses --> failure
  patch -- advances --> goal
  patch -- references --> artifact
  patch -- validated_by --> eval
  patch -- approved_by --> decision
  decision --> promoted
```

## What yoagent-state tracks

For a project yoyo is improving, the state layer should track:

- why a module exists
- why a dependency was added
- what goal and task the change served
- what test validates behavior
- what failure caused a patch
- what decision approved it
- what assumptions became stale
- what version introduced behavior

Concrete project diffs remain external. Reference them with `ArtifactRef` and `ProjectRef`.

## Demo

Run:

```bash
cargo run --example yoyo_evolve_demo
```

The demo records:

- a retry failure
- a base project reference
- a diff artifact
- changed file relations
- an eval result
- a human approval decision
- a promoted patch status

The resulting lineage includes:

```text
patch_retry_timeout
addresses -> failure_retry_timeout
modifies -> file:crates/yoagent-runtime/src/tool.rs
modifies -> file:crates/yoagent-runtime/tests/retry.rs
validated_by -> eval_retry_timeout
approved_by -> decision_promote_retry_timeout
```

```mermaid
flowchart LR
  patch["patch_retry_timeout"]
  failure["failure_retry_timeout"]
  source["file:crates/yoagent-runtime/src/tool.rs"]
  test["file:crates/yoagent-runtime/tests/retry.rs"]
  eval["eval_retry_timeout"]
  decision["decision_promote_retry_timeout"]

  patch -- addresses --> failure
  patch -- modifies --> source
  patch -- modifies --> test
  patch -- validated_by --> eval
  patch -- approved_by --> decision
```

## Implementation rule

Do not hide mutation.

Every meaningful project change should have:

- a patch
- an artifact reference
- evidence or expected effect
- an eval or approval decision before promotion

That makes yoyo’s project growth inspectable instead of magical.