KLIS-8: StateDigest Specification

1. Purpose

When an agent receives a DIE verdict, it must preserve its identity to ensure eventual progress. The StateDigest is the normative data structure that enables agent resurrection.

Without StateDigest:

• Restarted agents lose their priority timestamp
• Younger agents never become seniors
• Starvation is possible

With StateDigest:

• Priority is preserved across restarts
• Deadlock freedom is guaranteed
• Eventual progress is assured

2. Normative Fields

A KLIS-8 compliant StateDigest MUST contain:

| Field | Type | Required | Description | |-------|------|----------|-------------| | version | "1.0" | ✅ | Schema version | | identity.agent_id | string | ✅ | Unique agent identifier | | identity.priority_timestamp | number | ✅ | Original timestamp (MUST be preserved) | | identity.epoch | number | ✅ | Restart counter | | recovery.last_phase | enum | ✅ | PLANNING, REQUESTING, or EXECUTING | | recovery.pending_intents | string[] | ✅ | URIs the agent was attempting to lock |

3. Lifecycle

3.1. Creation

A StateDigest MUST be created when:

1. The Kernel issues a DIE verdict
2. The agent is about to exit with code 107

3.2. Persistence

The StateDigest MUST be persisted before process termination.

Storage location is implementation-defined, but common patterns include:

• .klock/state-digest.json in working directory
• Environment-specific state stores
• Passed via environment variable on restart

3.3. Restoration

On restart, an agent MUST:

1. Check for existing StateDigest
2. If found, restore identity.priority_timestamp
3. Increment identity.epoch
4. Resume with restored identity

3.4. Expiration

StateDigests MAY expire after a configurable timeout. Default recommendation: 5 minutes.

Expired digests SHOULD be treated as if no digest exists.

4. Example

Before DIE (Exit)

{
  "version": "1.0",
  "identity": {
    "agent_id": "agent_junior",
    "priority_timestamp": 2000,
    "epoch": 0
  },
  "recovery": {
    "last_phase": "REQUESTING",
    "pending_intents": ["FILE:/src/config.json"]
  },
  "timestamps": {
    "created_at": 1703458800000,
    "retry_after": 1703458802000
  }
}

After Restart (Resurrection)

The agent loads this digest and:

• Uses priority_timestamp: 2000 (not a new timestamp)
• Sets epoch: 1
• Retries the same intents

5. Security Considerations

• Digest Integrity: StateDigests SHOULD be signed or stored in a trusted location to prevent timestamp tampering.
• Priority Manipulation: Agents MUST NOT be able to forge lower (older) timestamps.

6. Non-Goals

• State Synchronization: KLIS-8 does not define how to sync state across distributed digests.
• Conflict Merging: Merging conflicting StateDigests is out of scope.