StagedHolon State Model: Versioning vs Graph-Only Updates

[evomimic]

1. Summary

Refine the StagedHolon state model to distinguish between:

• updates that require a new holon version, and
• updates that represent graph-only mutations (non-definitional relationships)

Introduce action-oriented staged states:

• ForUpdateNewVersion
• ForUpdateGraphOnly

and define a deterministic relationship source anchoring rule based on these states.

This enables commit logic to correctly determine:

• whether to persist a new holon version
• which holon version should serve as the source for relationship persistence

---

2. Problem Statement

The current StagedState model uses:

• New
• Fetched
• Changed

However, Changed conflates two fundamentally different kinds of mutation:

1. Definitional changes

   • property value updates
   • definitional relationship mutations
     → require a new holon version

2. Non-definitional changes

   • graph-level relationship updates
     → do not require a new holon version

This leads to ambiguity in commit behavior:

• Should a new version be written?
• Should relationships attach to the new version or the existing holon?

As a result:

• Commit logic is forced to infer intent from incomplete state
• Relationship anchoring is implicit and potentially inconsistent
• Forward and inverse persistence (Issue 1) cannot reliably determine the correct source holon

---

3. Goals

• Make commit behavior explicit and state-driven
• Distinguish versioning vs graph-only mutation
• Provide a deterministic rule for relationship source anchoring
• Align staging semantics with MAP’s distinction between:
  • holon identity (definitional)
  • graph topology (non-definitional)

---

4. Proposed Solution

4.1 Introduce Action-Oriented Staged States

Replace the ambiguous Changed state with:

• ForUpdateNewVersion

  • Definitional changes present
  • Requires update() (new holon version)

• ForUpdateGraphOnly

  • Only non-definitional relationship mutations
  • No new holon version required

Retain:

• ForCreate
• Fetched
• Committed
• Abandoned

These states express required commit actions, not mutation history.

---

4.2 State Transition Rules

• Fetched

  • non-definitional mutation → ForUpdateGraphOnly
  • definitional mutation → ForUpdateNewVersion

• ForUpdateGraphOnly

  • non-definitional mutation → remain
  • definitional mutation → ForUpdateNewVersion

• ForUpdateNewVersion

  • any mutation → remain

Definitional mutations dominate and upgrade state

---

4.3 Commit Behavior by State

At commit:

• ForCreate → create() new holon
• ForUpdateNewVersion → update() (new version)
• ForUpdateGraphOnly → no holon write
• Fetched → no holon write

In all cases:

• relationship persistence still occurs (see Issue 1)

---

4.4 Relationship Source Anchoring Rule

This is the key semantic introduced by this issue.

When persisting relationships:

• If state is ForUpdateNewVersion
  → relationships attach to the new holon version

• If state is ForUpdateGraphOnly or Fetched
  → relationships attach to the existing persisted holon

This rule applies to:

• forward SmartLink persistence
• inverse SmartLink persistence (Issue 1)

---

4.5 Integration with Commit Passes

• Pass 1

  • Determines whether a new holon version is created
  • Produces the correct LocalId for:
    • new version (if any), or
    • existing holon

• Pass 2

  • Must use the resolved source LocalId from Pass 1
  • Must not assume that the staged holon always becomes the source

---

4.6 Mutation API Implications

Mutation methods must trigger appropriate state transitions:

• Property updates → ForUpdateNewVersion
• Definitional relationship changes → ForUpdateNewVersion
• Non-definitional relationship changes → ForUpdateGraphOnly (if not already escalated)

This logic should be encapsulated within mutation helpers (e.g., mark_for_update_new_version, mark_for_graph_only_update).

---

5. Scope and Impact

Component	File(s)	Impact
StagedHolon state model	staged_holon.rs	New states + transitions
Nursery mutation logic	nursery.rs	State transitions on mutation
Commit Pass 1	commit_functions.rs	State-driven versioning logic
Commit Pass 2	commit_functions.rs	Updated source selection

Out of scope:

• Inverse relationship resolution logic (Issue 1)
• Duplicate detection and idempotency (Issue 3)
• Merge/reconciliation of divergent versions
• Cardinality constraints

---

6. Testing Considerations

• Verify correct state transitions for:

  • property updates
  • definitional relationship updates
  • non-definitional relationship updates

• Verify commit behavior:

  • new version created only for ForUpdateNewVersion
  • no version created for ForUpdateGraphOnly

• Verify relationship anchoring:

  • attaches to new version when appropriate
  • attaches to existing holon otherwise

• Verify compatibility with Issue 1:

  • inverse links use same resolved source

---

7. Definition of Done

• StagedState includes ForUpdateNewVersion and ForUpdateGraphOnly
• State transitions correctly reflect mutation types
• Commit Pass 1 uses state to determine version creation
• Commit Pass 2 uses resolved source from Pass 1
• Relationship anchoring rule is implemented and tested
• Existing tests pass without regression
• New tests validate state-driven commit behavior

---

8. Key Design Principles

• Staged states express required commit actions, not mutation history
• Definitional changes affect holon identity and require versioning
• Non-definitional changes affect graph topology only
• Relationship anchoring is deterministic and state-driven
• Forward and inverse persistence must use the same resolved source holon