mutate

Intent

Make controlled changes to persistent state with safety guarantees. This is the primary capability for modifications and REQUIRES a checkpoint for rollback capability.

CRITICAL: This capability requires checkpoint to have been called first.

Success criteria:

• State change applied correctly
• Previous state captured for rollback
• Change is verifiable
• Audit trail recorded

Compatible schemas:

• schemas/output_schema.yaml

Inputs

Parameter	Required	Type	Description
target	Yes	string	What to modify (file path, resource identifier)
operation	Yes	object	The modification to apply
checkpoint_id	Yes	string	Checkpoint ID for rollback (from checkpoint capability)

Procedure

1. Verify checkpoint exists: Ensure recovery is possible

   • Confirm checkpoint_id references valid checkpoint
   • Verify checkpoint covers the target
   • STOP if no valid checkpoint

2. Capture previous state: Record what will change

   • Read current state of target
   • Store for comparison and rollback
   • Document what specifically will change

3. Apply mutation: Make the change

   • Execute the specified operation
   • Use appropriate tool (Edit for files, Bash for commands)
   • Capture any errors during modification

4. Verify change: Confirm mutation succeeded

   • Read new state
   • Compare to expected result
   • Note any unexpected side effects

5. Record mutation: Document what changed

   • Store diff between previous and new state
   • Record timestamp and operation details
   • Link to checkpoint for audit trail

6. Return result: Provide complete mutation record

   • Include success/failure status
   • Provide before/after state
   • Reference checkpoint for rollback

Output Contract

Return a structured object:

success: boolean  # Whether mutation completed
target: string  # What was modified
operation: string  # What was done
previous_state:
  snapshot: any  # State before mutation
  captured_at: string  # When captured
new_state:
  snapshot: any  # State after mutation
  verified_at: string  # When verified
diff:
  type: string  # unified, structural, summary
  content: string  # The actual diff
checkpoint_id: string  # For rollback reference
rollback_command: string  # How to undo this change
evidence_anchors: ["file:line", "command:output"]