Implementing a Custom Conflict‑Resolution Strategy for OpenClaw Rating API Edge CRDT

1. Introduction

Real‑time rating systems must stay consistent across distributed nodes, even when updates arrive out of order. The OpenClaw Rating API leverages an Edge CRDT to guarantee eventual consistency without a central coordinator. However, the default conflict‑resolution (typically “first‑write‑wins”) may not satisfy every business rule. This tutorial walks senior engineers through building a custom merge function, applying a last‑write‑wins (LWW) strategy, and injecting domain‑specific logic for a rating service running on ubos.tech.

2. Recap of OpenClaw Rating API Edge CRDT Theory Guide

The earlier theory guide introduced the core concepts:

• CRDT (Conflict‑Free Replicated Data Type): a data structure that resolves conflicts automatically.
• Edge CRDT: a variant optimized for edge‑computing environments, where each node can apply updates locally.
• Rating payload: a JSON object { userId, itemId, score, timestamp } that is merged across replicas.

In the default configuration, OpenClaw merges two rating updates by selecting the one with the highest timestamp. While this works for simple “most recent wins” scenarios, many products need richer rules—such as ignoring stale scores, capping the maximum rating, or applying business‑level weighting.

3. Why Custom Conflict‑Resolution Matters

Consider a marketplace where:

1. Users can rate a product multiple times, but only the highest rating should affect the aggregate score.
2. Admins may override a rating for compliance reasons, and that override must always win.
3. Ratings older than 30 days should be ignored to prevent “ghost” votes from skewing analytics.

These rules cannot be expressed with the built‑in LWW merge alone. A custom merge function gives you the flexibility to encode such domain logic while still benefiting from the CRDT’s convergence guarantees.

4. Designing a Custom Merge Function

When designing the function, keep the MECE principle in mind: each rule should be mutually exclusive and collectively exhaustive. Below is a high‑level design checklist:

Below is a TypeScript signature that matches the OpenClaw SDK expectations:

type Rating = {
  userId: string;
  itemId: string;
  score: number;          // 1‑5
  timestamp: number;      // epoch ms
  adminOverride?: boolean;
};

type MergeResult = Rating;

/**
 * Custom merge for Edge CRDT rating objects.
 */
function customMerge(local: Rating, remote: Rating): MergeResult {
  // Implementation will be detailed in the next section.
}
    

5. Implementing Last‑Write‑Wins (LWW) Strategy

The LWW rule is the backbone of our merge. It selects the record with the newest timestamp, unless an admin override is present.

function lww(local: Rating, remote: Rating): Rating {
  // Admin override always wins
  if (local.adminOverride) return local;
  if (remote.adminOverride) return remote;

  // Otherwise, compare timestamps
  return local.timestamp >= remote.timestamp ? local : remote;
}
    

Notice the early return for adminOverride. This satisfies the “admin always wins” rule without breaking determinism.

6. Adding Application‑Specific Logic

Now we layer the extra business rules on top of the LWW result.

function applyBusinessRules(candidate: Rating, other: Rating): Rating {
  // Rule 1: Keep the highest score for the same user/item pair
  if (candidate.userId === other.userId && candidate.itemId === other.itemId) {
    if (candidate.score < other.score) {
      candidate = { ...candidate, score: other.score };
    }
  }

  // Rule 2: Discard ratings older than 30 days
  const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
  const now = Date.now();
  if (now - candidate.timestamp > THIRTY_DAYS_MS) {
    // Return a "tombstone" with score = 0 to neutralize the stale rating
    return { ...candidate, score: 0 };
  }

  // Rule 3: Clamp score to allowed range (1‑5)
  candidate.score = Math.min(5, Math.max(1, candidate.score));

  return candidate;
}
    

Finally, combine LWW and business rules into the customMerge function:

function customMerge(local: Rating, remote: Rating): MergeResult {
  // Step 1: Resolve using LWW
  const lwwResult = lww(local, remote);

  // Step 2: Apply domain‑specific rules against the losing side
  const final = applyBusinessRules(lwwResult, lwwResult === local ? remote : local);
  return final;
}
    

This composition ensures deterministic convergence while honoring all required constraints.

7. Code Walkthrough: Setup, Implementation, and Testing

7.1 Project Setup on UBOS

Start by creating a new UBOS project using the Web app editor on UBOS. Choose the “Node.js + TypeScript” template for rapid iteration.

1. Clone the starter repo:

git clone https://github.com/ubos-tech/openclaw-starter.git
cd openclaw-starter
npm install
    

2. Add the OpenClaw SDK as a dependency:

npm install @openclaw/sdk
    

7.2 Implementing the Custom Merge

Create a file src/merge/customMerge.ts and paste the functions from sections 5 and 6. Export the function for the CRDT configuration:

import { Rating } from '@openclaw/sdk';
export { customMerge };
    

7.3 Wiring the Merge into the Edge CRDT

In src/crdt/ratingCRDT.ts register the custom merge:

import { EdgeCRDT } from '@openclaw/sdk';
import { customMerge } from '../merge/customMerge';

const ratingCRDT = new EdgeCRDT<Rating>({
  merge: customMerge,
  // other config like replication endpoints
});

export default ratingCRDT;
    

7.4 Unit Tests with Jest

Write tests that cover each rule. Example:

import ratingCRDT from '../src/crdt/ratingCRDT';
import { Rating } from '@openclaw/sdk';

test('admin override wins over newer timestamp', () => {
  const admin: Rating = { userId: 'u1', itemId: 'i1', score: 2, timestamp: 1_600_000, adminOverride: true };
  const newer: Rating = { userId: 'u1', itemId: 'i1', score: 5, timestamp: 1_700_000 };
  const merged = ratingCRDT.merge(admin, newer);
  expect(merged).toEqual(admin);
});

test('stale rating older than 30 days becomes neutral', () => {
  const stale: Rating = { userId: 'u2', itemId: 'i2', score: 4, timestamp: Date.now() - 40 * 24 * 60 * 60 * 1000 };
  const fresh: Rating = { userId: 'u2', itemId: 'i2', score: 3, timestamp: Date.now() };
  const merged = ratingCRDT.merge(stale, fresh);
  expect(merged.score).toBe(0); // tombstone
});
    

7.5 Local Simulation with the Workflow Automation Studio

UBOS’s Workflow automation studio lets you spin up a simulated edge network. Deploy three nodes, push conflicting rating updates, and observe the converged state in the dashboard.

8. Deployment Considerations on ubos.tech

When moving from local testing to production, keep these factors in mind:

• Versioning: Tag the merge function as part of your CRDT module version. UBOS automatically rolls out compatible updates.
• Observability: Enable the built‑in metrics collector to track merge latency and conflict frequency.
• Security: Guard the adminOverride flag behind role‑based access control (RBAC) using UBOS’s partner program authentication hooks.
• Scalability: Edge CRDTs scale horizontally; ensure each edge node has sufficient memory for the rating state (approx. 200 KB per 10 k items).

For a concrete deployment example, see the OpenClaw hosting guide on UBOS, which walks you through provisioning a Docker‑based edge cluster, configuring TLS, and exposing the rating API behind a load balancer.

9. Conclusion and Next Steps

By crafting a custom merge function that blends a last‑write‑wins core with domain‑specific rules, you gain full control over how rating conflicts are resolved while preserving the convergence guarantees of the OpenClaw Edge CRDT. The steps covered—from design checklist to UBOS deployment—equip senior engineers to build robust, real‑time rating APIs that scale across edge nodes.

Ready to extend the pattern?

• Integrate OpenAI ChatGPT integration to auto‑moderate rating content before it reaches the CRDT.
• Leverage the AI marketing agents to surface top‑rated items in personalized campaigns.
• Explore the UBOS template marketplace for pre‑built dashboards that visualize rating trends in real time.

Implementing these extensions will further solidify your rating service as a cornerstone of data‑driven product experiences.