Skip to content

Commit 0fcb2cf

Browse files
simonovic86cursoragent
simonovic86
and
cursoragent
committed
docs(spec): introduce phase 0 runtime identity and migration invariants
Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent fde9eb7 commit 0fcb2cf

4 files changed

Lines changed: 569 additions & 0 deletions

File tree

‎TASKS.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,12 @@
2222

2323
---
2424

25+
## Phase 0 — Runtime Specification
26+
27+
[✓] Phase 0 Runtime Invariant Specification
28+
29+
---
30+
2531
## Phase 2 — Autonomy
2632

2733
[ ] Task 6 — Agent manifest validation & capability enforcement

‎docs/EXECUTION_INVARIANTS.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# Execution Invariants
2+
3+
## Purpose
4+
5+
This document defines the foundational runtime invariants governing Igor agent execution. These are conceptual contracts specifying what the runtime MUST guarantee regardless of implementation strategy.
6+
7+
This document does NOT prescribe wire formats, serialization schemas, cryptographic mechanisms, or distributed consensus protocols.
8+
9+
---
10+
11+
## Terminology
12+
13+
| Term | Definition |
14+
|------|-----------|
15+
| **identity** | Canonical logical execution identity of an agent. Uniquely identifies an agent across all nodes and across time. |
16+
| **authority** | The right held by exactly one node to advance an agent's checkpoint state. Authority is a runtime concept, separate from state durability. |
17+
| **checkpoint** | Atomic durable snapshot of agent state and metadata at a committed boundary. The canonical durability anchor for execution continuity. |
18+
| **migration** | Transfer of execution continuity — including identity, authority, and checkpoint lineage — from one node to another. |
19+
| **ticking** | Active execution of an agent's tick function by the authoritative node. A ticking instance is one that may produce side effects and advance state. |
20+
| **recovery-required** | A safety state entered when the runtime cannot determine unique authority. Execution is halted until authority is unambiguously resolved. |
21+
22+
---
23+
24+
## Runtime Identity Invariants
25+
26+
### EI-1: Single Active Instance
27+
28+
Igor guarantees **at-most-one active ticking instance** per agent identity at any point in time.
29+
30+
No two nodes may concurrently execute tick() for the same agent identity. This invariant holds across all operational states: normal execution, migration, recovery, and restart.
31+
32+
**Rationale:** Concurrent ticking would produce divergent state, violate checkpoint lineage, and break budget conservation. The single-instance invariant is the foundational safety property upon which all other guarantees depend.
33+
34+
---
35+
36+
## Continuity Invariants
37+
38+
### EI-2: Checkpoint Boundary Resumption
39+
40+
Agent execution MUST resume only from a committed checkpoint boundary.
41+
42+
A checkpoint represents a complete, durable, consistent snapshot of agent state. No execution may resume from partial state, uncommitted intermediary state, or reconstructed state.
43+
44+
**Rationale:** The checkpoint is the canonical durability anchor. All execution continuity flows through committed checkpoints. Resuming from any other source would violate state consistency guarantees.
45+
46+
### EI-3: Checkpoint Lineage Integrity
47+
48+
Each checkpoint is logically derived from the preceding checkpoint through a defined sequence of ticks. The lineage from initial state through all checkpoints forms a single ordered chain.
49+
50+
No checkpoint may exist outside this chain. No fork in checkpoint lineage is permitted.
51+
52+
**Rationale:** Forked lineage implies concurrent state mutation, which violates EI-1. Linear checkpoint lineage is both a consequence of and evidence for the single-instance invariant.
53+
54+
---
55+
56+
## Authority Invariants
57+
58+
### EI-4: Authority and Durability Separation
59+
60+
Execution authority and state durability are separate concepts.
61+
62+
- **Authority** defines which node may advance checkpoint state (i.e., tick and produce new checkpoints).
63+
- **Durability** defines where checkpoint data is persisted.
64+
65+
A node may hold a durable copy of a checkpoint without holding authority to advance it. Authority is a runtime grant, not a storage property.
66+
67+
**Rationale:** Separating these concepts allows checkpoint data to be replicated or cached for migration preparation without granting execution rights. This distinction is essential for safe migration handoff.
68+
69+
### EI-5: Singular Authority
70+
71+
For any given agent identity, at most one node holds execution authority at any time.
72+
73+
Authority is never shared, split, or held concurrently by multiple nodes. If the runtime cannot determine which node holds authority, execution enters recovery-required state.
74+
75+
**Rationale:** Dual authority would permit concurrent ticking, violating EI-1.
76+
77+
---
78+
79+
## Safety Invariants
80+
81+
### EI-6: Safety Over Liveness
82+
83+
Under uncertainty, Igor MUST prefer safety over liveness.
84+
85+
When the runtime cannot confirm that all invariants hold — for example, during network partition, ambiguous authority, or incomplete migration — the correct response is to pause execution rather than risk invariant violation.
86+
87+
Temporary execution pauses are acceptable. Invariant violations are not.
88+
89+
**Rationale:** An agent that pauses temporarily loses only liveness. An agent that violates single-instance or checkpoint lineage invariants may suffer irrecoverable state corruption, budget divergence, or identity compromise.
90+
91+
### EI-7: Fail-Stop on Invariant Violation
92+
93+
If the runtime detects an invariant violation, the affected agent MUST be stopped immediately. The runtime MUST NOT attempt silent recovery or automatic state reconciliation.
94+
95+
**Rationale:** Silent recovery risks masking fundamental correctness failures. Igor's design philosophy is to fail loudly on invariant violations.
96+
97+
---
98+
99+
## Migration Invariants
100+
101+
### EI-8: Migration Single-Instance Preservation
102+
103+
Migration MUST NOT produce concurrent ticking instances at any point during the transfer process.
104+
105+
At no moment may both the source node and target node be ticking the same agent identity. The handoff of execution authority is a serialized event: the source must relinquish authority before the target begins ticking.
106+
107+
**Rationale:** Migration is a transfer of authority, not a duplication. Concurrent ticking during migration would violate EI-1 and could fork checkpoint lineage.
108+
109+
### EI-9: Migration Pause Acceptability
110+
111+
Migration MAY temporarily pause execution.
112+
113+
A period during which no node is ticking the agent is acceptable during migration. The agent is not lost — its state is durable in the committed checkpoint. Liveness is temporarily sacrificed to preserve safety.
114+
115+
**Rationale:** Follows from EI-6. The gap between source ceasing and target beginning is a safe liveness pause, not a failure.
116+
117+
### EI-10: Migration Checkpoint Continuity
118+
119+
Migration MUST preserve checkpoint lineage.
120+
121+
The target node resumes from the same committed checkpoint that the source node last produced. No state is lost, invented, or interpolated during migration.
122+
123+
**Rationale:** Migration transfers execution continuity. The checkpoint is the continuity anchor. Breaking checkpoint lineage would make migration indistinguishable from state corruption.
124+
125+
---
126+
127+
## Invariant Summary
128+
129+
| ID | Invariant | Category |
130+
|----|-----------|----------|
131+
| EI-1 | At-most-one active ticking instance per identity | Runtime Identity |
132+
| EI-2 | Resume only from committed checkpoint boundary | Continuity |
133+
| EI-3 | Checkpoint lineage forms single ordered chain | Continuity |
134+
| EI-4 | Authority and durability are separate concepts | Authority |
135+
| EI-5 | At most one node holds execution authority | Authority |
136+
| EI-6 | Prefer safety over liveness under uncertainty | Safety |
137+
| EI-7 | Fail-stop on invariant violation | Safety |
138+
| EI-8 | Migration must not produce concurrent ticking | Migration |
139+
| EI-9 | Migration may temporarily pause execution | Migration |
140+
| EI-10 | Migration must preserve checkpoint lineage | Migration |
141+
142+
---
143+
144+
## Relationship to Existing Invariants
145+
146+
This document formalizes execution-level invariants as conceptual contracts. The existing [INVARIANTS.md](./INVARIANTS.md) defines operational invariants (I1–I10) with enforcement status and detection mechanisms. The two documents are complementary:
147+
148+
- **INVARIANTS.md** — operational invariants with implementation-level enforcement detail.
149+
- **EXECUTION_INVARIANTS.md** — formal specification of runtime identity, authority, and migration contracts.
150+
151+
The invariants in this document are consistent with and extend the guarantees described in INVARIANTS.md. No conflicts exist between the two specifications.
152+
153+
---
154+
155+
## Document Status
156+
157+
**Type:** Phase 0 Runtime Specification
158+
**Scope:** Conceptual contracts only — no wire formats, serialization, or cryptographic mechanisms.
159+
**Authority:** Normative for all future implementation of execution identity, authority, and migration behavior.

‎docs/MIGRATION_CONTINUITY.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# Migration Continuity
2+
3+
## Purpose
4+
5+
This document defines the conceptual migration contract governing how Igor transfers execution continuity between nodes. It formalizes migration guarantees, overlap constraints, and failure safety invariants.
6+
7+
This document does NOT prescribe wire formats, serialization schemas, cryptographic mechanisms, or distributed consensus protocols.
8+
9+
---
10+
11+
## Terminology
12+
13+
| Term | Definition |
14+
|------|-----------|
15+
| **identity** | Canonical logical execution identity of an agent. Uniquely identifies an agent across all nodes and across time. |
16+
| **authority** | The right held by exactly one node to advance an agent's checkpoint state. Authority is a runtime concept, separate from state durability. |
17+
| **checkpoint** | Atomic durable snapshot of agent state and metadata at a committed boundary. The canonical durability anchor for execution continuity. |
18+
| **migration** | Transfer of execution continuity — including identity, authority, and checkpoint lineage — from one node to another. |
19+
| **ticking** | Active execution of an agent's tick function by the authoritative node. A ticking instance is one that may produce side effects and advance state. |
20+
| **recovery-required** | A safety state entered when the runtime cannot determine unique authority. Execution is halted until authority is unambiguously resolved. |
21+
22+
---
23+
24+
## Migration Definition
25+
26+
### MC-1: Migration as Continuity Transfer
27+
28+
Migration transfers execution continuity from a source node to a target node. It is a structured handoff of:
29+
30+
- **Agent identity** — the target inherits the same canonical identity.
31+
- **Execution authority** — the target becomes the sole ACTIVE_OWNER.
32+
- **Checkpoint lineage** — the target resumes from the source's last committed checkpoint.
33+
34+
Migration is not cloning, replication, or restart. It is a transfer of a single execution thread across physical boundaries.
35+
36+
### MC-2: Migration Scope
37+
38+
Migration encompasses:
39+
40+
- Authority lifecycle transition (see [OWNERSHIP_AND_AUTHORITY.md](./OWNERSHIP_AND_AUTHORITY.md)).
41+
- Checkpoint data transfer from source to target.
42+
- Execution resumption on target from committed checkpoint.
43+
- Retirement of source node's role for this agent identity.
44+
45+
Migration does not encompass:
46+
47+
- Creation of new agent identities.
48+
- Modification of checkpoint content.
49+
- Parallel or speculative execution.
50+
51+
---
52+
53+
## Safe Migration Guarantees
54+
55+
### MC-3: Checkpoint Lineage Preservation
56+
57+
Migration MUST preserve checkpoint lineage.
58+
59+
The target node resumes from the exact committed checkpoint produced by the source node. The checkpoint chain before and after migration forms a single unbroken sequence. No checkpoint is lost, skipped, modified, or fabricated during migration.
60+
61+
**Relationship:** Enforces EI-3 (checkpoint lineage integrity) and EI-10 (migration checkpoint continuity).
62+
63+
### MC-4: Execution Identity Preservation
64+
65+
Migration MUST preserve execution identity.
66+
67+
The agent identity on the target node is identical to the agent identity on the source node. From the agent's perspective, migration is transparent — execution continues under the same identity with the same state.
68+
69+
**Relationship:** Enforces OA-1 (canonical logical identity).
70+
71+
### MC-5: Single-Authority Guarantee
72+
73+
Migration MUST maintain the single-authority guarantee at all times.
74+
75+
At no point during migration may two nodes simultaneously hold execution authority for the same agent identity. Authority transfer is serialized: the source relinquishes before the target assumes.
76+
77+
**Relationship:** Enforces EI-1 (single active instance), EI-5 (singular authority), and OA-5 (transfer serialization).
78+
79+
---
80+
81+
## Overlap Constraints
82+
83+
### MC-6: Permitted Preparation Activities
84+
85+
During migration preparation — after the target has been identified but before authority transfer — the target node MAY:
86+
87+
- **Load checkpoint data** — receive and store the checkpoint from the source.
88+
- **Validate state** — verify checkpoint integrity and format.
89+
- **Prepare environment** — initialize WASM sandbox, allocate resources, pre-load agent binary.
90+
91+
These activities are read-only with respect to agent state. They prepare the target to assume authority but do not constitute execution.
92+
93+
### MC-7: Prohibited Preparation Activities
94+
95+
During migration preparation, the target node MUST NOT:
96+
97+
- **Tick** — execute the agent's tick function.
98+
- **Produce side effects** — perform any action attributable to the agent's execution.
99+
- **Mutate durable state** — write new checkpoints, modify existing checkpoints, or alter any persistent state associated with the agent identity.
100+
101+
These prohibitions hold until the target has formally assumed authority (ACTIVE_OWNER state).
102+
103+
**Rationale:** Preparation activities that mutate state or produce side effects would constitute unauthorized execution, violating the single-authority invariant. The target node is a passive recipient until authority transfer completes.
104+
105+
### MC-8: Source Node Constraints During Handoff
106+
107+
After initiating handoff (HANDOFF_INITIATED), the source node MUST NOT:
108+
109+
- Begin new tick executions.
110+
- Produce new checkpoints beyond the handoff checkpoint.
111+
112+
The source node MAY:
113+
114+
- Complete any in-progress checkpoint operation.
115+
- Serve checkpoint data to the target.
116+
- Maintain the agent's durable state until transfer completes.
117+
118+
---
119+
120+
## Failure Safety Matrix
121+
122+
The following matrix defines invariant outcomes for migration failure scenarios. Each scenario specifies what MUST be true regardless of implementation, not how the failure is handled.
123+
124+
### FS-1: Crash During Migration
125+
126+
**Scenario:** A node crashes during an active migration — either the source or target fails unexpectedly.
127+
128+
**Invariant outcomes:**
129+
130+
- At most one node may tick the agent after recovery.
131+
- The last committed checkpoint from the verified authority chain is the recovery anchor.
132+
- If the source crashed after relinquishing authority but the target did not confirm assumption, the agent enters RECOVERY_REQUIRED state.
133+
- If the source crashed before relinquishing authority, the source retains authority upon restart and may resume from its last committed checkpoint.
134+
- If the target crashed after assuming authority, the target retains authority upon restart and resumes from the transferred checkpoint.
135+
- No state fabrication or interpolation is permitted during recovery.
136+
137+
### FS-2: Network Partition During Transfer
138+
139+
**Scenario:** Network connectivity between source and target is lost during authority transfer.
140+
141+
**Invariant outcomes:**
142+
143+
- Neither node may assume the transfer completed unless it received explicit confirmation.
144+
- If the source cannot confirm target assumption, the agent enters RECOVERY_REQUIRED state.
145+
- If the target cannot confirm source retirement, the target MUST NOT begin ticking until authority is unambiguously resolved.
146+
- A partition MUST NOT cause both nodes to independently resume ticking.
147+
- The last committed checkpoint remains the recovery anchor.
148+
- Liveness may be lost for the duration of the partition — this is acceptable per safety-over-liveness (EI-6).
149+
150+
### FS-3: Duplicate Migration Attempts
151+
152+
**Scenario:** Multiple migration requests are issued for the same agent identity concurrently or in rapid succession.
153+
154+
**Invariant outcomes:**
155+
156+
- At most one migration may proceed for a given agent identity at any time.
157+
- Concurrent migration attempts MUST be serialized or rejected.
158+
- A second migration request while the agent is in HANDOFF_INITIATED or HANDOFF_PENDING state MUST be refused.
159+
- No migration attempt may bypass the authority lifecycle.
160+
- If conflicting migration attempts result in ambiguous authority, the agent enters RECOVERY_REQUIRED state.
161+
162+
### FS-4: Stale Checkpoint Restart
163+
164+
**Scenario:** A node attempts to resume an agent from a checkpoint that is not the latest in the authority chain — for example, due to a stale local copy after migration has occurred.
165+
166+
**Invariant outcomes:**
167+
168+
- A node MUST NOT tick an agent unless it holds execution authority for that agent identity.
169+
- Possession of a checkpoint does not confer authority (EI-4).
170+
- If a node detects that its checkpoint is not authoritative (e.g., authority has been transferred), it MUST NOT resume the agent.
171+
- If a stale restart is detected after ticking has begun, the agent MUST enter RECOVERY_REQUIRED state.
172+
- The authoritative checkpoint chain — not local storage — determines the valid recovery point.
173+
174+
---
175+
176+
## Failure Safety Summary
177+
178+
| Scenario | Invariant Outcome |
179+
|----------|-------------------|
180+
| Source crash before relinquishing | Source retains authority, resumes from checkpoint |
181+
| Source crash after relinquishing | RECOVERY_REQUIRED until authority resolved |
182+
| Target crash after assuming | Target retains authority, resumes from checkpoint |
183+
| Network partition during transfer | RECOVERY_REQUIRED, no dual ticking |
184+
| Duplicate migration attempts | Serialized or rejected, at most one proceeds |
185+
| Stale checkpoint restart | Authority check required, no unauthorized ticking |
186+
187+
---
188+
189+
## Relationship to Other Specifications
190+
191+
This document operationalizes migration-specific guarantees defined in:
192+
193+
- **[EXECUTION_INVARIANTS.md](./EXECUTION_INVARIANTS.md)** — EI-1 (single instance), EI-6 (safety over liveness), EI-8 through EI-10 (migration invariants).
194+
- **[OWNERSHIP_AND_AUTHORITY.md](./OWNERSHIP_AND_AUTHORITY.md)** — Authority lifecycle states and transfer serialization rules.
195+
196+
The failure safety matrix provides invariant outcomes for scenarios that exercise these contracts under adverse conditions.
197+
198+
---
199+
200+
## Document Status
201+
202+
**Type:** Phase 0 Runtime Specification
203+
**Scope:** Conceptual contracts only — no wire formats, serialization, or cryptographic mechanisms.
204+
**Authority:** Normative for all future implementation of agent migration behavior and failure recovery.

0 commit comments

Comments
 (0)