Weekly Temporal Scheduling & Overlap Scoring

The 10,080-Minute Coordinate System

Instead of synchronizing bulky calendar feeds or querying external time services during matching, NodeHash projects each peer's working windows into integer minute offsets within a single standardized week:

This numeric mapping gives the matching engine three distinct performance benefits:

• Constant-Time Translation: Converting local times to UTC requires only basic integer multiplication and modulo arithmetic.
• Compact Storage: A user's entire weekly schedule compresses down to an array of four-byte integer pairs.
• Fast Intersections: Finding shared free time between candidates runs in linear time using a two-pointer sweep algorithm.

Timezone Normalization & Daylight Saving Adjustments

Because users live in different parts of the world, they submit their recurring availability using their local wall-clock time and IANA timezone name (for instance, America/New_York or Asia/Tokyo). The node engine converts each local window into normalized UTC intervals before candidate scoring.

Handling Daylight Saving Transitions

Hardcoding static offsets like UTC-5 or UTC+1 causes schedule desynchronization whenever daylight saving time begins or ends. To prevent missed handoffs, NodeHash evaluates timezone offsets dynamically.

When a matching loop is calculated, the system runs Intl.DateTimeFormat with the user's declared IANA timezone against the active timestamp. This inspects standard time and daylight saving time transitions on the fly, calculating the exact current offset in minutes without requiring manual profile updates.

Setting Recurring Working Windows

You can define recurring availability on both your global profile and individual supply items. The JSON schema requires your IANA timezone identifier and an array of recurring windows:

{
  "time_zone": "America/Los_Angeles",
  "available_time_windows": [
    {
      "day_of_week": 1,
      "start_time": "09:00",
      "end_time": "17:00",
      "is_negotiable": false
    },
    {
      "day_of_week": 3,
      "start_time": "10:00",
      "end_time": "18:00",
      "is_negotiable": true
    },
    {
      "day_of_week": 5,
      "start_time": "13:00",
      "end_time": "16:00",
      "is_negotiable": true
    }
  ]
}

Each window object contains four essential properties:

• day_of_week (Integer, 0 to 6): Specifies the calendar day, where 0 represents Sunday and 6 represents Saturday.
• start_time (String, HH:MM): The beginning of your active window in 24-hour local wall-clock format.
• end_time (String, HH:MM): The end of your active window. If earlier than start time, the window spans across local midnight.
• is_negotiable (Boolean): Flags whether you are willing to shift this window during term negotiation. Setting this to true grants a scoring bonus during candidate matching.

Profile Update Command

Submit your availability to your node endpoint with a standard authenticated request:

curl -X PATCH https://api.nodehash.org/api/v1/users/profile \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "temporal": {
      "time_zone": "Europe/London",
      "available_time_windows": [
        {
          "day_of_week": 2,
          "start_time": "14:00",
          "end_time": "18:00",
          "is_negotiable": true
        }
      ]
    }
  }'

Overlap Scoring Mechanics

When scoring potential barter matches, the engine calculates mutual overlap between candidate schedules. The baseline threshold for full schedule compatibility is 5 hours (300 minutes).

Multi-Party Schedule Intersections (K ≤ 3)

In bilateral trades ($K = 2$), checking availability involves just one pair of schedules. In trilateral cycles ($K = 3$), all three peers must find a mutually compatible schedule window or agree to asynchronous delivery.

The matching engine evaluates multi-party intersections iteratively using a sweep-line algorithm:

1. Sort & Merge: All individual windows for each peer are converted to UTC and merged to eliminate internal overlaps.
2. Pairwise Sweep: The engine takes Participant A and Participant B, scanning sorted intervals with two pointers to compute their shared intersection set $I_{A,B}$.
3. Sequential Pruning: If $I_{A,B}$ is empty, the cycle temporal score immediately drops to zero. The engine avoids wasting clock cycles on third-party calculations.
4. Trilateral Intersection: If $I_{A,B}$ contains valid intervals, the engine intersects $I_{A,B}$ with Participant C's intervals to generate the final trilateral intersection $I_{A,B,C}$.
5. Slot Formatting: The resulting UTC intervals are partitioned back into calendar days and converted to standard 24-hour strings for user presentation.

{
  "success": true,
  "data": {
    "overlapMinutes": 240,
    "overlapScore": 0.9000,
    "commonSlots": [
      {
        "day_of_week": 2,
        "start_time": "14:00",
        "end_time": "16:00"
      },
      {
        "day_of_week": 4,
        "start_time": "14:00",
        "end_time": "16:00"
      }
    ]
  }
}

Once peers discover candidate matches with favorable temporal scores, they move into term negotiation to finalize milestones and schedule commitments.