Skip to content

Commit 8f86623

Browse files
committed
docs(vrs): clarify conformance proof boundaries
1 parent e1b7ccb commit 8f86623

2 files changed

Lines changed: 48 additions & 43 deletions

File tree

docs/vrs/02-agent-spec/requirements.md

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
## Context
44

55
The canonical Agent Spec and its proof corpus live in
6-
[compoundingtech/evals at commit `b3cd5fbd98c11179a4555d0f9bbccfe98351a734`](https://github.com/compoundingtech/evals/blob/b3cd5fbd98c11179a4555d0f9bbccfe98351a734/AGENT-SPEC.md).
6+
[compoundingtech/evals at commit `e9b53e79b05b1c0e1d7eea02db2eaba47376fe05`](https://github.com/compoundingtech/evals/blob/e9b53e79b05b1c0e1d7eea02db2eaba47376fe05/AGENT-SPEC.md).
77
st2 is one implementation. Another implementation, including a future st3, can
88
target the same contract and proofs.
99

@@ -40,15 +40,15 @@ Field lookup: [F01](./spec.md#f01), [F02](./spec.md#f02),
4040
healing of independently absent or dead work. A provider field has no core
4141
effect until a provider lowers it into core fields.
4242

43-
- **SPEC-R02 Fail closed at the smallest unproven local scope.** Before a
44-
change, validate the complete local owner, render dependency, and conflict
45-
component. Prove the current owner of each affected process and file. Partial,
46-
unreadable, ambiguous, or conflicting input retains the latest locally proved
47-
ownership. It never proves removal. Destructive action requires proof that
48-
binds the exact catalog, host, owner, task ID, and live incarnation (one task
49-
generation). Work without this proof stays in `hold`. Independent proved
50-
components can proceed. No prior synchronized snapshot, deletion record, or
51-
CAS is required.
43+
- **SPEC-R02 Do not change work whose proof is incomplete.** Before a change,
44+
validate all input that can affect the related agents, tasks, and files.
45+
Prove the current owner of each affected process and file. Partial, unreadable,
46+
ambiguous, or conflicting input retains the latest locally proved ownership.
47+
It never proves removal. Destructive action requires proof that binds the
48+
exact catalog, host, owner, task ID, and live incarnation (one task generation).
49+
Work without this proof stays in `hold`. Independent agents, tasks, and files
50+
can proceed when their input and ownership proof are complete. No prior
51+
synchronized snapshot, deletion record, or CAS is required.
5252

5353
- **SPEC-R03 Preserve live work unless the field rule changes it.** Metadata,
5454
live context, render data, Resource data, and future policy do not restart a
@@ -68,15 +68,15 @@ Field lookup: [F01](./spec.md#f01), [F02](./spec.md#f02),
6868
order, receipt, or proof. Catalog skew can cause temporary overlap or absence;
6969
each host retains its local last-known-good ownership.
7070

71-
- **SPEC-R05 Plan and execute each local component in phases.** Plan every
72-
action, refusal, proof, conflict, and rollback condition before mutation. Use
73-
`FENCE`, `REMOVE/QUIESCE`, `MATERIALIZE`, `ADD/BOOT`, `NOTIFY`, then
74-
`VERIFY/REPORT`, and omit empty phases. Fence and remove an exact conflicting
75-
old incarnation before an add. Use final desired bytes for the add. A deletion
76-
requires explicit desired state and ownership proof, and never removes a
77-
catalog source declaration. Roll back only when rollback is proved; otherwise
78-
hold or refuse before a dependent phase. Explicit replacement authority is
79-
required for a drifted live incarnation.
71+
- **SPEC-R05 Plan every related action before mutation.** Plan every action,
72+
refusal, proof, conflict, and rollback condition for the related agents,
73+
tasks, and files. Use `FENCE`, `REMOVE/QUIESCE`, `MATERIALIZE`, `ADD/BOOT`,
74+
`NOTIFY`, then `VERIFY/REPORT`, and omit empty phases. Fence and remove an
75+
exact conflicting old incarnation before an add. Use final desired bytes for
76+
the add. A deletion requires explicit desired state and ownership proof, and
77+
never removes a catalog source declaration. Roll back only when rollback is
78+
proved; otherwise hold or refuse before a dependent phase. Explicit
79+
replacement authority is required for a drifted live incarnation.
8080

8181
- **SPEC-R06 Send one quiet event after commit.** When a committed workspace,
8282
render, or Resource change is visible to a survivor, write one coalesced

docs/vrs/02-agent-spec/spec.md

Lines changed: 29 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,13 @@ before destructive action. Each host acts only on its local projection. Fence
1111
and remove before a conflicting add. Notify surviving agents only after commit.
1212

1313
A dry-run makes no writes. Dry-run and quiet status name only affected IDs,
14-
with the change, action or refusal, and proof scope. They include desired and
15-
observed fingerprints and the exact incarnation when relevant. `hold` waits
16-
without the requested lifecycle change. `refuse` makes no change because
17-
validation or proof failed.
14+
with the change, action or refusal, and what the proof covers. They include
15+
desired and observed fingerprints and the exact incarnation when relevant.
16+
`hold` waits without the requested lifecycle change. `refuse` makes no change
17+
because validation or proof failed.
1818

1919
Each **Authoring** link points to the canonical evals Agent Spec at exact commit
20-
`b3cd5fbd98c11179a4555d0f9bbccfe98351a734`, which is pinned to st2
20+
`e9b53e79b05b1c0e1d7eea02db2eaba47376fe05`, which is pinned to st2
2121
`9887b28`. It is the authoring authority, not proof of current st2 runtime
2222
behavior. **st2 source** and **Evidence** links show this implementation on the
2323
PR base.
@@ -59,7 +59,7 @@ Authoring: [pinned discovery and host][evals-discovery]. st2 source:
5959
<h3 id="f04">F04 <code>type</code></h3>
6060

6161
An omitted value and `service` have the same effect. Any other value refuses
62-
the owner component before launch, write, or teardown.
62+
changes to the related agent, tasks, and files before launch, write, or teardown.
6363

6464
Authoring: [pinned complete declaration][evals-fields]. st2 source:
6565
[`JobType` and `RawSpec::job_type`](../../../crates/agent-spec/src/spec.rs).
@@ -135,7 +135,7 @@ fingerprint. Absent or dead work boots with the latest inputs.
135135

136136
A healthy mismatch stays alive as `drifted` or `unknown`; report both
137137
fingerprints. Command drift stays visible and does not restart automatically.
138-
Replacement needs task-scoped authority and a fresh exact-incarnation check.
138+
Replacement needs authority for that task and a fresh exact-incarnation check.
139139
An `env` key named `PTY_ROOT` is only a task launch input.
140140

141141
Authoring: [pinned tasks][evals-tasks] and [environment][evals-environment]. The
@@ -147,7 +147,8 @@ Evidence: [spawn construction](../../../src/run.rs).
147147

148148
Agent or task `keep`, restart `attempts`, `interval`, `delay`, and `mode`, and
149149
task `lifecycle` are future policy. Adopt healthy work. `adopt-only` holds absent
150-
or dead work; `service` reconciles it normally. Invalid policy refuses the owner.
150+
or dead work; `service` reconciles it normally. Invalid policy refuses changes
151+
to the related agent and tasks.
151152

152153
Authoring: [pinned complete declaration][evals-fields]. The
153154
[pinned explicit-task list][evals-task-fields] and st2 `9887b28` predate task
@@ -188,9 +189,10 @@ Authoring: [pinned complete declaration][evals-fields]. st2 source:
188189

189190
<h3 id="f16">F16 Invalid or incomplete state</h3>
190191

191-
Refuse the smallest affected local component when desired or actual state is
192+
Refuse changes to an agent, task, or file when its desired or actual state is
192193
unreadable, invalid, ambiguous, or conflicting. Keep last-known-good ownership
193-
and perform no destructive action there. Independent proved work can continue.
194+
and perform no destructive action to that work. Independent agents, tasks, and
195+
files can continue when their input and ownership proof are complete.
194196

195197
Authoring: [pinned validation, health, and lifecycle][evals-lifecycle]. st2
196198
source: [`RawSpec` and `AgentSpec`](../../../crates/agent-spec/src/spec.rs).
@@ -227,8 +229,9 @@ from this fixed order:
227229
6. **VERIFY/REPORT:** verify exact results; roll back only when proved,
228230
otherwise hold or refuse.
229231

230-
Independent proved components progress separately. The order does not
231-
coordinate hosts or authorize replacement of drifted work.
232+
Independent agents, tasks, and files progress separately when their input and
233+
ownership proof are complete. The order does not coordinate hosts or authorize
234+
replacement of drifted work.
232235

233236
## Current implementation gaps
234237

@@ -248,7 +251,8 @@ coordinate hosts or authorize replacement of drifted work.
248251
- **G06, notifications:** inbox and DING exist, but reconciliation writes no
249252
stable change event. [Message](../../../src/message.rs) and
250253
[DING](../../../src/ding/mod.rs)
251-
- **G07, planning/reporting:** st2 has no component transaction or true dry-run;
254+
- **G07, planning/reporting:** st2 cannot plan and commit all related agent,
255+
task, and file changes as one operation, and it has no true dry-run;
252256
`materialize-only` writes. See [#53](https://github.com/compoundingtech/st2/issues/53)
253257
and [runner](../../../src/run.rs).
254258
- **G08, moved intent:** parser, status, and executor support are absent; syntax
@@ -272,14 +276,15 @@ coordinate hosts or authorize replacement of drifted work.
272276
shared receipt.
273277
- Moved intent rejects cycles, conflicts, and host changes. It removes before
274278
add unless a future atomic address change can preserve the process.
275-
- A refused component does not block independent work. Every result names the
276-
affected IDs, action, and proof scope.
277-
278-
[evals-discovery]: https://github.com/compoundingtech/evals/blob/b3cd5fbd98c11179a4555d0f9bbccfe98351a734/AGENT-SPEC.md#discovery-identity-and-host
279-
[evals-fields]: https://github.com/compoundingtech/evals/blob/b3cd5fbd98c11179a4555d0f9bbccfe98351a734/AGENT-SPEC.md#complete-declaration-shape
280-
[evals-supported-fields]: https://github.com/compoundingtech/evals/blob/b3cd5fbd98c11179a4555d0f9bbccfe98351a734/AGENT-SPEC.md#L73-L95
281-
[evals-tasks]: https://github.com/compoundingtech/evals/blob/b3cd5fbd98c11179a4555d0f9bbccfe98351a734/AGENT-SPEC.md#compact-and-explicit-tasks
282-
[evals-task-fields]: https://github.com/compoundingtech/evals/blob/b3cd5fbd98c11179a4555d0f9bbccfe98351a734/AGENT-SPEC.md#L147-L151
283-
[evals-environment]: https://github.com/compoundingtech/evals/blob/b3cd5fbd98c11179a4555d0f9bbccfe98351a734/AGENT-SPEC.md#environment-and-expansion
284-
[evals-render]: https://github.com/compoundingtech/evals/blob/b3cd5fbd98c11179a4555d0f9bbccfe98351a734/AGENT-SPEC.md#render-contract
285-
[evals-lifecycle]: https://github.com/compoundingtech/evals/blob/b3cd5fbd98c11179a4555d0f9bbccfe98351a734/AGENT-SPEC.md#validation-health-and-lifecycle
279+
- A refusal for one related set of agents, tasks, or files does not block
280+
independent work whose input and ownership proof are complete. Every result
281+
names the affected IDs, action, and what the proof covers.
282+
283+
[evals-discovery]: https://github.com/compoundingtech/evals/blob/e9b53e79b05b1c0e1d7eea02db2eaba47376fe05/AGENT-SPEC.md#discovery-identity-and-host
284+
[evals-fields]: https://github.com/compoundingtech/evals/blob/e9b53e79b05b1c0e1d7eea02db2eaba47376fe05/AGENT-SPEC.md#complete-declaration-shape
285+
[evals-supported-fields]: https://github.com/compoundingtech/evals/blob/e9b53e79b05b1c0e1d7eea02db2eaba47376fe05/AGENT-SPEC.md#L79-L101
286+
[evals-tasks]: https://github.com/compoundingtech/evals/blob/e9b53e79b05b1c0e1d7eea02db2eaba47376fe05/AGENT-SPEC.md#compact-and-explicit-tasks
287+
[evals-task-fields]: https://github.com/compoundingtech/evals/blob/e9b53e79b05b1c0e1d7eea02db2eaba47376fe05/AGENT-SPEC.md#L153-L157
288+
[evals-environment]: https://github.com/compoundingtech/evals/blob/e9b53e79b05b1c0e1d7eea02db2eaba47376fe05/AGENT-SPEC.md#environment-and-expansion
289+
[evals-render]: https://github.com/compoundingtech/evals/blob/e9b53e79b05b1c0e1d7eea02db2eaba47376fe05/AGENT-SPEC.md#render-contract
290+
[evals-lifecycle]: https://github.com/compoundingtech/evals/blob/e9b53e79b05b1c0e1d7eea02db2eaba47376fe05/AGENT-SPEC.md#validation-health-and-lifecycle

0 commit comments

Comments
 (0)