diff --git a/README.md b/README.md index 5596c01..6f71beb 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/src/stamps.ts b/src/stamps.ts index dd43bf9..c085d2d 100644 --- a/src/stamps.ts +++ b/src/stamps.ts @@ -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]); @@ -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]; } /** diff --git a/test/lww.test.ts b/test/lww.test.ts index 264e6b1..3931c8f 100644 --- a/test/lww.test.ts +++ b/test/lww.test.ts @@ -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", @@ -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)", () => {