Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,10 @@ receives the migrated document over the struct stream and must not call this.
`stampKey(op)`, `compareStampKeys(a, b)`, `writeTarget(op)`,
`stampTargetKey(op)`, `codePointCompare(a, b)`. You need these only if you are
building conflict UI or your own bookkeeping — `applyOps` uses them internally.
Stamp counters are non-negative safe integers; `stampKey` and
`compareStampKeys` throw `RangeError` when a direct caller supplies a counter
outside that domain. An absent stamp still falls back to the envelope's
`base_version` and `actor`, including the existing `0`/empty-string defaults.

### Follower read surface and document internals

Expand Down
16 changes: 13 additions & 3 deletions src/stamps.ts
Original file line number Diff line number Diff line change
Expand Up @@ -33,14 +33,24 @@ export function codePointCompare(a: string, b: string): -1 | 0 | 1 {
return ra === rb ? 0 : ra < rb ? -1 : 1;
}

function validStampCounter(counter: number): number {
if (!Number.isSafeInteger(counter) || counter < 0) {
throw new RangeError("Stamp counter must be a non-negative safe integer");
}
return counter;
}

/**
* Total-order comparison of two stamp keys `[base_version, actor, op_id]`:
* element-wise, first difference decides — numeric on `base_version`,
* code-point order on `actor` and `op_id` (vocabulary §3 / §8.1). Two keys
* compare equal only if they are the same op.
* compare equal only if they are the same op. Counters outside the valid
* non-negative-safe-integer domain are rejected rather than compared.
*/
export function compareStampKeys(a: StampKey, b: StampKey): -1 | 0 | 1 {
if (a[0] !== b[0]) return a[0] < b[0] ? -1 : 1;
const aCounter = validStampCounter(a[0]);
const bCounter = validStampCounter(b[0]);
if (aCounter !== bCounter) return aCounter < bCounter ? -1 : 1;
const byActor = codePointCompare(a[1], b[1]);
if (byActor !== 0) return byActor;
return codePointCompare(a[2], b[2]);
Expand All @@ -56,7 +66,7 @@ export function stampKey(op: WireOp): StampKey {
Array.isArray(op.stamp) && op.stamp.length === 2
? op.stamp
: ([op.base_version ?? 0, op.actor ?? ""] as const);
return [Number(stamp[0] ?? 0), String(stamp[1] ?? ""), op.op_id];
return [validStampCounter(Number(stamp[0] ?? 0)), String(stamp[1] ?? ""), op.op_id];
}

/**
Expand Down
94 changes: 94 additions & 0 deletions test/lww.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,63 @@ describe("compareStampKeys (freeze doc §8.1)", () => {
expect(compareStampKeys(k, [...k] as StampKey)).toBe(0);
});

it.each([Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY])(
"rejects an invalid direct StampKey counter %s on either side",
(counter) => {
const valid: StampKey = [1, "alice", "a".repeat(32)];
const invalid: StampKey = [counter, "bob", "b".repeat(32)];
expect(() => compareStampKeys(invalid, valid)).toThrowError(
new RangeError("Stamp counter must be a non-negative safe integer"),
);
expect(() => compareStampKeys(valid, invalid)).toThrowError(
new RangeError("Stamp counter must be a non-negative safe integer"),
);
},
);

it("is antisymmetric and transitive over asymmetric valid keys", () => {
const lowCounter: StampKey = [1, "zulu", "f".repeat(32)];
const lowOpId: StampKey = [2, "alice", "a".repeat(32)];
const highOpId: StampKey = [2, "alice", "f".repeat(32)];
const highActor: StampKey = [2, "bob", "a".repeat(32)];

for (const [lower, higher] of [
[lowCounter, lowOpId],
[lowOpId, highOpId],
[highOpId, highActor],
[lowCounter, highOpId],
[lowCounter, highActor],
] as const) {
expect(compareStampKeys(lower, higher)).toBe(-1);
expect(compareStampKeys(higher, lower)).toBe(1);
}
});

it("accepts both safe-counter boundaries and rejects finite values outside them", () => {
const op: SetWidgetOp = {
op: "set_widget",
op_id: "f".repeat(32),
actor: "envelope-actor",
base_version: 7,
stamp: [0, "stamp-actor"],
node_id: 1,
widget: "steps",
value: 1,
};
for (const counter of [0, Number.MAX_SAFE_INTEGER]) {
const key: StampKey = [counter, "stamp-actor", op.op_id];
expect(stampKey({ ...op, stamp: [counter, "stamp-actor"] })).toEqual(key);
expect(compareStampKeys(key, key)).toBe(0);
}
for (const counter of [-1, 0.5, Number.MAX_SAFE_INTEGER + 1]) {
const invalid: StampKey = [counter, "stamp-actor", op.op_id];
const valid: StampKey = [0, "stamp-actor", op.op_id];
expect(() => stampKey({ ...op, stamp: [counter, "stamp-actor"] })).toThrow(RangeError);
expect(() => compareStampKeys(invalid, valid)).toThrow(RangeError);
expect(() => compareStampKeys(valid, invalid)).toThrow(RangeError);
}
});

it("stampKey falls back to [base_version, actor] when stamp is absent", () => {
const op = {
op: "set_widget",
Expand All @@ -81,6 +138,43 @@ describe("compareStampKeys (freeze doc §8.1)", () => {
} as unknown as SetWidgetOp;
expect(stampKey(op)).toEqual([4, "alice", "c".repeat(32)]);
});

it.each([Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY])(
"rejects an invalid authoritative stamp counter %s",
(counter) => {
const op = {
op: "set_widget",
op_id: "d".repeat(32),
actor: "envelope-actor",
base_version: 7,
stamp: [counter, "stamp-actor"],
node_id: 1,
widget: "steps",
value: 1,
} as unknown as SetWidgetOp;
expect(() => stampKey(op)).toThrowError(
new RangeError("Stamp counter must be a non-negative safe integer"),
);
},
);

it.each([Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY])(
"rejects an invalid fallback counter %s",
(counter) => {
const op = {
op: "set_widget",
op_id: "e".repeat(32),
actor: "fallback-actor",
base_version: counter,
node_id: 1,
widget: "steps",
value: 1,
} as unknown as SetWidgetOp;
expect(() => stampKey(op)).toThrowError(
new RangeError("Stamp counter must be a non-negative safe integer"),
);
},
);
});

describe("LWW vector application (both orders)", () => {
Expand Down
Loading