State Ownership

Control who can write to which fields

StateOwnership controls which agents can write to which parts of shared state. Prevents agents from overwriting each other’s work.

Basic Usage

from splinter.coordination import StateOwnership

ownership = StateOwnership()

# Researcher owns research.* fields
ownership.register("researcher", ["research.*"])

# Writer owns content.* fields  
ownership.register("writer", ["content.*"])

# Check permissions
ownership.check_write("researcher", "research.findings")  # ✓ OK
ownership.check_write("researcher", "content.article")    # ✗ Raises

Pattern Matching

Use glob patterns for paths:

# Matches research.findings, research.sources, etc.
ownership.register("researcher", ["research.*"])

# Matches content.draft, content.final, content.revisions.v1, etc.
ownership.register("writer", ["content.**"])  # ** = recursive

# Exact match only
ownership.register("admin", ["config.setting"])

Multiple Owners

Sometimes multiple agents need write access:

# Both can write to shared.*
ownership.register("researcher", ["research.*", "shared.*"])
ownership.register("writer", ["content.*", "shared.*"])

# Or use allow_multiple
ownership.register("shared.*", allow_multiple=True)
ownership.add_owner("shared.*", "researcher")
ownership.add_owner("shared.*", "writer")

Ownership Modes

from splinter.coordination import OwnershipMode

# Strict: Only owner can write (default)
ownership = StateOwnership(mode=OwnershipMode.STRICT)

# Advisory: Log warnings but allow writes
ownership = StateOwnership(mode=OwnershipMode.ADVISORY)

# Audit: Log all writes, no enforcement
ownership = StateOwnership(mode=OwnershipMode.AUDIT)

Transferring Ownership

# Researcher finishes, transfers to writer
ownership.transfer("research.findings", from_agent="researcher", to_agent="writer")

# Now writer can modify research.findings

Checking Ownership

# Who owns this path?
owner = ownership.get_owner("research.findings")  # "researcher"

# What does this agent own?
paths = ownership.get_owned_paths("researcher")  # ["research.*"]

# Can this agent write here?
can_write = ownership.can_write("researcher", "research.findings")  # True

Integration with SharedState

from splinter.coordination import SharedState, StateOwnership, ProtectedState

state = SharedState()
ownership = StateOwnership()
ownership.register("researcher", ["research.*"])

# Wrap with protection
protected = ProtectedState(state, ownership)

# Now writes are checked
protected.set("researcher", "research.findings", [1, 2, 3])  # ✓
protected.set("researcher", "content.article", "...")        # ✗ Raises

Best Practices

Define ownership before agents run

Set up all ownership rules before the workflow starts.

Use meaningful path prefixes

research.*, content.*, review.* - clear who owns what.

Start strict, relax if needed

Better to be too restrictive than too permissive.

Log ownership violations

Even in advisory mode, violations indicate design issues.