Tools for agents: Vector-clock comparison and merge

Detect ordered or concurrent clock states and compute their componentwise maximum with comparison witnesses.

Connect with MCP

{
  "mcpServers": {
    "super-agent-tools": {
      "url": "https://app.getsupers.com/sites/agent-vector-clock/mcp"
    }
  }
}
Streamable HTTP · No API key · Stateless

Use this URL in any client supporting remote Streamable HTTP MCP. Calls return structured JSON; inputs are processed without persistence.

Call compare_vector_clocks

Relation describes left relative to right: before means every left counter is <= right and at least one is smaller; after is the reverse; equal means all components match; concurrent means each clock is ahead on at least one actor. Absent actors count as zero. Empty clocks are allowed and equal explicit all-zero clocks. Actor IDs are case-sensitive exact strings; counters must be nonnegative JSON integers, not booleans or decimal numbers. The merged clock contains the union of actors, including explicit zero entries, with componentwise maximum counters. It does not increment any actor, merge payloads, resolve semantic conflicts, authenticate history, or persist state. Causal interpretation requires clocks maintained correctly under a shared actor identity scheme; supplied counters alone cannot prove actual event history. Clock timestamps are not wall-clock times. Do not truncate actors if exact comparison is required. Background: https://www.allthingsdistributed.com/2007/10/amazons_dynamo.html

Input and output schemas
{
  "name": "compare_vector_clocks",
  "title": "Vector-clock comparison and merge",
  "description": "Compare componentwise nonnegative vector clocks, treating absent actors as zero. Return equal/before/after/concurrent, witnesses and merged maximum counters. Does not increment counters or merge payloads.",
  "inputSchema": {
    "properties": {
      "left": {
        "additionalProperties": {
          "type": "integer"
        },
        "title": "Left",
        "type": "object"
      },
      "right": {
        "additionalProperties": {
          "type": "integer"
        },
        "title": "Right",
        "type": "object"
      }
    },
    "required": [
      "left",
      "right"
    ],
    "title": "compare_vector_clocksArguments",
    "type": "object"
  },
  "outputSchema": {
    "additionalProperties": true,
    "title": "compare_vector_clocksDictOutput",
    "type": "object"
  },
  "icons": null,
  "annotations": {
    "title": null,
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "meta": null,
  "execution": null
}

Run the example to see the actual result.

HTTP alternative

POST https://app.getsupers.com/sites/agent-vector-clock/call
Content-Type: application/json

{
  "left": {
    "builder": 3,
    "reviewer": 1
  },
  "right": {
    "builder": 2,
    "reviewer": 2
  }
}

The HTTP and MCP interfaces execute the same implementation. Validation errors are returned explicitly. See the tool notes above for its supported inputs and behavior.

A componentwise order distinguishes concurrent clocks

Read the explanation

The documented example compares left builder three reviewer one with right builder two reviewer two. Left is ahead for builder, but right is ahead for reviewer. Neither is componentwise less than or equal to the other, so the relation is concurrent. The purple corner takes the maximum on each axis: builder three reviewer two. The connecting lines illustrate coordinate selection, not events being executed or counters being incremented. This offline preview does not call the remote tool. Before means every left counter is no larger than the corresponding right counter, with at least one strictly smaller. For left two one and right three two, both components increase and left is before right. After is the reverse. Equal requires all effective components to match. These are partial order relations, not chronological times or comparisons of the sum of counters. Absent actors count as zero. Empty clocks therefore compare equal to explicit all-zero clocks. The merged result contains the union of actors, including explicit zeros, and does not increment any actor. Identifiers are case-sensitive and counters must be nonnegative JSON integers, excluding booleans and decimals. The result merges counters rather than document payloads, authenticating history or resolving semantic conflicts. Correct causal interpretation depends on correctly maintained clocks and a shared actor identity scheme.

Vector Clock Partial Ordering and Least Upper Bound Merge

How does componentwise comparison identify whether two distributed vector clocks are strictly ordered or concurrent, and what does their merged state represent?

Vector clocks track logical causality across independent actors by maintaining non-negative integer counters. Comparing two clocks componentwise evaluates each actor's counter independently: if all counters of one clock are less than or equal to the other and at least one is strictly less, one causally precedes the other; if neither clock dominates on all actors, they are concurrent. Merging takes the componentwise maximum, forming the least upper bound without altering domain payloads.

The comparison assumes actors follow consistent string identifiers and that counter increments reflect real logical steps. It evaluates purely mathematical counters: it does not verify message signatures, guarantee wall-clock freshness, increment the recipient's own counter, or resolve semantic payload conflicts.

Try a worked example

In the JSON arguments field, keep the default input where left is {"builder": 3, "reviewer": 1} and right is {"builder": 2, "reviewer": 2}. When you click 'Run tool', the structured result updates from the placeholder text to a JSON object showing 'relation': 'concurrent', identifying 'builder' in 'left_ahead_actors' and 'reviewer' in 'right_ahead_actors', with a 'merged_clock' of {"builder": 3, "reviewer": 2}.

Causality and Concurrency in Distributed Systems

In distributed architectures like Amazon Dynamo, vector clocks capture causality between different versions of an object by associating actor-counter pairs with state updates. When one clock's counters are less than or equal to another's across all actors, the earlier version is an ancestor and can be superseded syntactically. Amazon's Dynamo | All Things Distributed

When parallel updates occur without mutual awareness, neither clock dominates every actor component, producing concurrent branches that require higher-level application reconciliation. Amazon's Dynamo | All Things Distributed

Componentwise Evaluation and Least Upper Bound

This stateless implementation aligns actors across both clocks, treating any omitted actor in either clock as counter zero. It collects which actors have higher values on the left versus the right, returning 'equal', 'before', 'after', or 'concurrent' along with the actor witness lists.

The merged clock calculates the least upper bound across the union of participating actors by setting each actor's counter to max(left, right). This operation reconciles the clock horizons, though merging domain payloads or assigning the next logical sequence remains the responsibility of the calling application. Amazon's Dynamo | All Things Distributed

Sources and further reading