[milestone Milestone 4] Define checkpoint/fork architecture model and core data structures

[telleroutlook]

🤖 Auto-filed as prerequisite sub-issue for checkpoint-evidence schema.

Repo: WasmAgent/wasmagent-protocol
Milestone: Milestone 4 — Evidence types beyond execution

Problem

The checkpoint-evidence.schema.json implementation is blocked because it references domain concepts that lack established definitions:

• checkpoint_id - what constitutes a checkpoint identifier?
• parent_run_id - relationship to execution runs?
• fork_of - how are forks identified and tracked?
• state_digest - what state is being digested?

Approach

Create the foundational architecture documentation and type definitions that checkpoint-evidence.schema.json will depend on.

1. Create checkpoint/fork architecture design document

Create docs/design/checkpoint-fork-architecture.md with:

Checkpoint Definition:

• What a checkpoint represents in the WasmAgent protocol (e.g., a snapshot of execution state at a specific point)
• When checkpoints are created (e.g., at explicit agent checkpoints, after tool executions, at intervals)
• What checkpoint state includes (e.g., memory, registers, linear memory, stack)

Fork Definition:

• What constitutes a fork (e.g., divergence from a parent execution path)
• When forks occur (e.g., branching decisions, parallel exploration, replay with different inputs)
• How forks relate to checkpoints (fork originates from a checkpoint)

Relationships:

• Checkpoint → Run: many-to-one (a checkpoint belongs to one run; a run can have multiple checkpoints)
• Fork → Checkpoint: one-to-one (a fork originates from exactly one checkpoint)
• Fork → Run: one-to-one (a fork creates a new run with the forked execution)

2. Define core data structure formats

Add type definitions to docs/design/checkpoint-fork-architecture.md:

checkpoint_id: String with format checkpoint:{run_id}:{sequence_number}

• Example: checkpoint:run-abc123:5 (5th checkpoint of run run-abc123)
• MUST be unique within a protocol instance
• Sequence number increments monotonically within a run

parent_run_id: String reference to existing run_id from execution model

• Format: Matches existing run_id format (e.g., run-{uuid} or as defined in execution schema)
• References the run that created this checkpoint

fork_of: Optional string with format checkpoint:{checkpoint_id}

• Present only when this run is a fork of another execution
• References the checkpoint from which the fork originated
• Null for root/non-forked runs

state_digest: String (cryptographic hash)

• Algorithm: SHA-256 (default) or as specified in digest_algorithm field
• Computed over: serialized checkpoint state including:
  • Linear memory contents
  • Stack state
  • Global variables
  • Any additional Wasm state
• Format: {algorithm}:{hex_digest} (e.g., sha256:abcd1234...)

3. Evidence model documentation

Add to docs/design/checkpoint-fork-architecture.md:

What checkpoint-evidence asserts:

• A specific checkpoint existed at a specific point in execution
• The checkpoint state digest is as claimed
• The checkpoint was created by the claimed run
• (Optional) The checkpoint is signed by the execution environment

Who signs checkpoint-evidence:

• The execution environment/runtime that captured the checkpoint
• Signature proves the checkpoint was created by a trusted environment

Verification requirements:

• Verify signature against trusted execution environment key
• Verify checkpoint_id format validity
• Verify parent_run_id references an existing run
• Verify fork_of references an existing checkpoint (if present)
• Verify state_digest format and re-compute if checkpoint state available

4. Create prerequisite schemas (if needed)

If checkpoints or forks need their own schemas (beyond what checkpoint-evidence provides), create:

• schemas/aep/checkpoint.schema.json (if checkpoints are independent artifacts)
• schemas/aep/fork.schema.json (if forks are independent records)

If these are only referenced within checkpoint-evidence, document that they are inline types defined in checkpoint-evidence.schema.json rather than standalone schemas.

Files

• docs/design/checkpoint-fork-architecture.md - CREATE (new file)
• schemas/aep/checkpoint.schema.json - CREATE (only if checkpoints are independent artifacts)
• schemas/aep/fork.schema.json - CREATE (only if forks are independent records)
• schemas/aep/checkpoint-evidence.schema.json - NOT in this issue (blocked, unblocked by this issue)

Acceptance Criteria

• docs/design/checkpoint-fork-architecture.md exists and contains:
  • Checkpoint definition with when/how they're created
  • Fork definition with when/how they occur
  • Relationship diagram (text or mermaid) showing checkpoint/run/fork relationships
  • Evidence model section defining what checkpoint-evidence asserts, who signs it, and how to verify
  • Core data structure format definitions (checkpoint_id, parent_run_id, fork_of, state_digest)
• Core data types have formal format definitions with examples
• Relationship to existing run/execution models is specified
• Design doc specifies whether checkpoint/fork schemas are standalone or inline types
• If standalone schemas are needed, schemas/aep/checkpoint.schema.json and/or schemas/aep/fork.schema.json exist with valid JSON Schema
• Design doc can be used as reference for implementing schemas/aep/checkpoint-evidence.schema.json

Unblocks

• Original issue: Add schemas/aep/checkpoint-evidence.schema.json (issue [milestone Milestone 4 ] Add schemas/aep/checkpoint-evidence.schema.json — signed checkpoint/fork rec... #78)

[telleroutlook]

🤖 Auto-analysis: this issue has been parked 2 times and needs human attention.

Analysis: This is a chicken-and-egg deadlock: defining checkpoint/fork architecture (prerequisite) requires validation against checkpoint-evidence schema, but that schema's precondition is the architecture being defined. The issue asks the bot to establish foundational concepts that must be validated by referencing the very schema they block—a circular dependency that verify-first cannot resolve automatically.

[telleroutlook]

🤖 Auto-analysis: this issue has been parked 3 times and needs human attention.

Analysis: This issue requires fundamental architecture design decisions about domain concepts (checkpoints, forks, state digests) that cannot be determined automatically from existing code or documentation; these are design choices requiring stakeholder consensus on the WasmAgent protocol's execution model.

[telleroutlook]

🤖 Auto-analysis: this issue has been parked 3 times and needs human attention.

Analysis: This issue requires foundational design decisions about protocol semantics (what constitutes a checkpoint/fork in WasmAgent architecture) that cannot be determined automatically - these are architectural choices requiring human domain expertise, not discoverable implementation details.

[telleroutlook]

🤖 Auto-analysis: this issue has been parked 3 times and needs human attention.

Analysis: LLM unavailable

[telleroutlook]

🤖 Auto-analysis: this issue has been parked 3 times and needs human attention.

Analysis: failed to parse LLM response: Looking at this issue, I need to analyze why verify-first keeps returning NOT_YET after 3 attempts.
... [truncated]

[telleroutlook]

🤖 Auto-analysis: this issue has been parked 3 times and needs human attention.

Analysis: LLM unavailable

[telleroutlook]

🤖 Auto-analysis: this issue has been parked 3 times and needs human attention.

Analysis: failed to parse LLM response: Based on the issue analysis, this is a case where the bot is trying to implement checkpoint-evidence... [truncated]

[telleroutlook]

🤖 Auto-analysis: this issue has been parked 3 times and needs human attention.

Analysis: LLM unavailable

[telleroutlook]

🤖 Auto-analysis: this issue has been parked 3 times and needs human attention.

Analysis: LLM unavailable

[telleroutlook]

🤖 Auto-analysis: this issue has been parked 3 times and needs human attention.

Analysis: LLM unavailable

[telleroutlook]

🤖 Auto-analysis: this issue has been parked 3 times and needs human attention.

Analysis: LLM unavailable