Class SpaceStateCrdt

java.lang.Object
ai.badmonkey.agentspaces.space.crdt.SpaceStateCrdt
public final class SpaceStateCrdt extends Object
The replica state of one space as a delta-mergeable CRDT (spec §7.3): an OR-Set of entries keyed by EntryId, each carrying its own EntryState. Replicas that have seen the same updates are identical, and partitions merge deterministically; the replicated space grows on this class, and the CRDT laws are pinned by randomized convergence tests.

Immutable; operations return new states. Tombstone garbage collection (gc(long, long)) drops entries that are no longer live once twice the maximum lease has passed since their lease expired, and leaves merge semantics unchanged.

  • Method Details

    • empty

      public static SpaceStateCrdt empty()
      Returns the empty state.

    • of

      public static SpaceStateCrdt of(EntryId entryId, EntryState state)
      Wraps one entry's exact state as a mergeable value. Replication uses this to merge a remote replica's per-entry state into the local replica.
      Parameters:
      entryId - the entry
      state - the entry's state
      Returns:
      a one-entry CRDT holding exactly that state

    • add

      public SpaceStateCrdt add(EntryRecord record, Dot addDot, LwwRegister<LeaseInfo> lease)
      Applies a local write.
      Parameters:
      record - the written record
      addDot - the writing replica's dot
      lease - the write lease register
      Returns:
      the updated state

    • remove

      public SpaceStateCrdt remove(EntryId entryId)
      Withdraws an entry by removing its observed add dots.
      Parameters:
      entryId - the entry to withdraw
      Returns:
      the updated state; unchanged when the entry is unknown here

    • complete

      public SpaceStateCrdt complete(EntryId entryId)
      Marks an entry completed. Monotone: merges never resurrect it.
      Parameters:
      entryId - the completed entry
      Returns:
      the updated state; unchanged when the entry is unknown here

    • setLease

      public SpaceStateCrdt setLease(EntryId entryId, LwwRegister<LeaseInfo> leaseWrite)
      Applies a lease write (take claim, renewal, reappearance).
      Parameters:
      entryId - the entry
      leaseWrite - the lease write, stamped by the writer's HLC
      Returns:
      the updated state; unchanged when the entry is unknown here

    • merge

      public SpaceStateCrdt merge(SpaceStateCrdt other)
      Merges another replica's state into this one.
      Parameters:
      other - the other replica's state
      Returns:
      the merged state

    • liveRecords

      public List<EntryRecord> liveRecords()
      Returns the records of currently present entries.

    • state

      public Optional<EntryState> state(EntryId entryId)
      Returns one entry's state.
      Parameters:
      entryId - the entry
      Returns:
      the state, when known to this replica

    • knownEntries

      public int knownEntries()
      Returns the number of entries this replica knows about, tombstones included.

    • collectable

      public static boolean collectable(EntryState state, long nowMillis, long maxLeaseMillis)
      Whether one entry's state is a collectable tombstone (spec §7.3): the entry is no longer live (completed, withdrawn, or its write lease has lapsed) and its lease expired at least twice the maximum lease ago, so every replica that could still learn of the transition has had two full lease periods to do so.
      Parameters:
      state - the entry's state
      nowMillis - the current time, epoch milliseconds
      maxLeaseMillis - the longest lease observed for the space
      Returns:
      true when the entry may be dropped

    • collectable

      public Set<EntryId> collectable(long nowMillis, long maxLeaseMillis)
      Returns the ids of entries collectable(EntryState, long, long) would drop now.
      Parameters:
      nowMillis - the current time, epoch milliseconds
      maxLeaseMillis - the longest lease observed for the space
      Returns:
      the collectable entry ids

    • gc

      public SpaceStateCrdt gc(long nowMillis, long maxLeaseMillis)
      Garbage-collects tombstones (spec §7.3): drops every entry that is no longer live and whose lease expired more than twice the maximum lease ago. Merge semantics are unchanged; a collected tombstone re-offered by a lagging replica is simply collectable again, and the replicated space refuses such offers at the door.
      Parameters:
      nowMillis - the current time, epoch milliseconds
      maxLeaseMillis - the longest lease observed for the space
      Returns:
      the state without collectable entries; this when nothing qualifies

    • without

      public SpaceStateCrdt without(Set<EntryId> ids)
      Returns a state without the given entries.
      Parameters:
      ids - the entries to drop
      Returns:
      the reduced state; this when none were known

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object