add specs for clocks

src/realm/logical-clock.spec.ts

···
+import {IdentBrand} from '#realm/protocol/brands'
+import {compare, explode, generate} from '#realm/protocol/timestamp'
+import {beforeEach, describe, expect, it, jest} from '@jest/globals'
+import {LogicalClock} from './logical-clock'
+
+describe('LogicalClock', () => {
+  let identAlice: ReturnType<typeof IdentBrand.generate>
+  let identBob: ReturnType<typeof IdentBrand.generate>
+
+  beforeEach(() => {
+    identAlice = IdentBrand.generate()
+    identBob = IdentBrand.generate()
+  })
+
+  describe('constructor', () => {
+    it('creates a clock with no initial timestamp', () => {
+      const clock = new LogicalClock(identAlice)
+
+      expect(clock.actor).toBe(identAlice)
+      expect(clock.latest()).toBeNull()
+    })
+
+    it('creates a clock with an initial timestamp', () => {
+      const initialTimestamp = generate(identAlice, 1000, 0)
+      const clock = new LogicalClock(identAlice, initialTimestamp)
+
+      expect(clock.actor).toBe(identAlice)
+      expect(clock.latest()).toBe(initialTimestamp)
+    })
+  })
+
+  describe('actor', () => {
+    it('returns the identity of the clock owner', () => {
+      const clock = new LogicalClock(identAlice)
+
+      expect(clock.actor).toBe(identAlice)
+    })
+  })
+
+  describe('latest', () => {
+    it('returns null initially when no timestamp is set', () => {
+      const clock = new LogicalClock(identAlice)
+
+      expect(clock.latest()).toBeNull()
+    })
+
+    it('returns the latest timestamp after generating one', () => {
+      const clock = new LogicalClock(identAlice)
+      const timestamp = clock.now()
+
+      expect(clock.latest()).toBe(timestamp)
+    })
+
+    it('returns the bootstrapped timestamp', () => {
+      const initialTimestamp = generate(identAlice, 1000, 0)
+      const clock = new LogicalClock(identAlice, initialTimestamp)
+
+      expect(clock.latest()).toBe(initialTimestamp)
+    })
+  })
+
+  describe('now', () => {
+    it('generates a monotonically increasing timestamp', () => {
+      const clock = new LogicalClock(identAlice)
+
+      const ts1 = clock.now()
+      const ts2 = clock.now()
+      const ts3 = clock.now()
+
+      expect(compare(ts1, ts2)).toBeLessThan(0)
+      expect(compare(ts2, ts3)).toBeLessThan(0)
+    })
+
+    it('increments counter for timestamps in same second', () => {
+      const clock = new LogicalClock(identAlice)
+
+      const ts1 = clock.now()
+      const ts2 = clock.now()
+
+      const {seconds: s1, counter: c1} = explode(ts1)
+      const {seconds: s2, counter: c2} = explode(ts2)
+
+      if (s1 === s2) {
+        expect(c2).toBe(c1 + 1)
+      }
+    })
+
+    it('uses the clock actor identity', () => {
+      const clock = new LogicalClock(identAlice)
+      const timestamp = clock.now()
+
+      const {identid} = explode(timestamp)
+      expect(identid).toBe(identAlice)
+    })
+
+    it('updates latest timestamp', () => {
+      const clock = new LogicalClock(identAlice)
+
+      expect(clock.latest()).toBeNull()
+
+      const ts1 = clock.now()
+      expect(clock.latest()).toBe(ts1)
+
+      const ts2 = clock.now()
+      expect(clock.latest()).toBe(ts2)
+    })
+
+    it('handles rapid successive calls', () => {
+      const clock = new LogicalClock(identAlice)
+      const timestamps = []
+
+      for (let i = 0; i < 100; i++) {
+        timestamps.push(clock.now())
+      }
+
+      // All timestamps should be strictly ordered
+      for (let i = 0; i < timestamps.length - 1; i++) {
+        expect(compare(timestamps[i], timestamps[i + 1])).toBeLessThan(0)
+      }
+    })
+
+    it('generates timestamps with current physical time', () => {
+      const clock = new LogicalClock(identAlice)
+      const beforeSeconds = Math.round(Date.now() / 1000)
+
+      const timestamp = clock.now()
+
+      const afterSeconds = Math.round(Date.now() / 1000)
+      const {seconds} = explode(timestamp)
+
+      // Timestamp seconds should be within the test execution window
+      expect(seconds).toBeGreaterThanOrEqual(beforeSeconds)
+      expect(seconds).toBeLessThanOrEqual(afterSeconds)
+    })
+  })
+
+  describe('tick', () => {
+    it('advances clock with newer timestamp', () => {
+      const clock = new LogicalClock(identAlice)
+      const ts1 = generate(identAlice, 1000, 0)
+
+      const result = clock.tick(ts1)
+
+      expect(result).toBe(ts1)
+      expect(clock.latest()).toBe(ts1)
+    })
+
+    it('does not regress clock with older timestamp', () => {
+      const clock = new LogicalClock(identAlice)
+      const ts1 = generate(identAlice, 2000, 0)
+      const ts2 = generate(identAlice, 1000, 0)
+
+      clock.tick(ts1)
+      const result = clock.tick(ts2)
+
+      expect(result).toBe(ts1)
+      expect(clock.latest()).toBe(ts1)
+    })
+
+    it('accepts timestamp from different actor', () => {
+      const clock = new LogicalClock(identAlice)
+      const bobTimestamp = generate(identBob, 1000, 0)
+
+      const result = clock.tick(bobTimestamp)
+
+      expect(result).toBe(bobTimestamp)
+      expect(clock.latest()).toBe(bobTimestamp)
+    })
+
+    it('maintains monotonicity when mixing now() and tick()', () => {
+      const clock = new LogicalClock(identAlice)
+
+      const ts1 = clock.now()
+      const externalTs = generate(identBob, 9999999999, 0) // Far future
+      clock.tick(externalTs)
+      const ts2 = clock.now()
+
+      expect(compare(ts1, externalTs)).toBeLessThan(0)
+      expect(compare(externalTs, ts2)).toBeLessThanOrEqual(0)
+    })
+
+    it('returns latest timestamp even when not advancing', () => {
+      const clock = new LogicalClock(identAlice)
+      const ts1 = generate(identAlice, 2000, 0)
+      const ts2 = generate(identAlice, 1000, 0)
+
+      clock.tick(ts1)
+      const result = clock.tick(ts2)
+
+      expect(result).toBe(ts1)
+    })
+
+    it('handles equal timestamps idempotently', () => {
+      const clock = new LogicalClock(identAlice)
+      const timestamp = generate(identAlice, 1000, 0)
+
+      const result1 = clock.tick(timestamp)
+      const result2 = clock.tick(timestamp)
+
+      expect(result1).toBe(timestamp)
+      expect(result2).toBe(timestamp)
+      expect(clock.latest()).toBe(timestamp)
+    })
+  })
+
+  describe('tick event', () => {
+    it('dispatches tick event when clock advances', () => {
+      const clock = new LogicalClock(identAlice)
+      const listener = jest.fn()
+
+      clock.addEventListener('tick', listener)
+
+      const timestamp = generate(identAlice, 1000, 0)
+      clock.tick(timestamp)
+
+      expect(listener).toHaveBeenCalledTimes(1)
+      expect(listener).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'tick',
+          detail: timestamp,
+        }),
+      )
+    })
+
+    it('does not dispatch event when clock does not advance', () => {
+      const clock = new LogicalClock(identAlice)
+      const listener = jest.fn()
+
+      const ts1 = generate(identAlice, 2000, 0)
+      const ts2 = generate(identAlice, 1000, 0)
+
+      clock.tick(ts1)
+      clock.addEventListener('tick', listener)
+      clock.tick(ts2) // Older, should not trigger event
+
+      expect(listener).not.toHaveBeenCalled()
+    })
+
+    it('dispatches event on each now() call', () => {
+      const clock = new LogicalClock(identAlice)
+      const listener = jest.fn()
+
+      clock.addEventListener('tick', listener)
+
+      clock.now()
+      clock.now()
+      clock.now()
+
+      expect(listener).toHaveBeenCalledTimes(3)
+    })
+
+    it('allows multiple listeners', () => {
+      const clock = new LogicalClock(identAlice)
+      const listener1 = jest.fn()
+      const listener2 = jest.fn()
+
+      clock.addEventListener('tick', listener1)
+      clock.addEventListener('tick', listener2)
+
+      const timestamp = generate(identAlice, 1000, 0)
+      clock.tick(timestamp)
+
+      expect(listener1).toHaveBeenCalledTimes(1)
+      expect(listener2).toHaveBeenCalledTimes(1)
+    })
+
+    it('can remove listeners', () => {
+      const clock = new LogicalClock(identAlice)
+      const listener = jest.fn()
+
+      clock.addEventListener('tick', listener)
+      clock.tick(generate(identAlice, 1000, 0))
+
+      expect(listener).toHaveBeenCalledTimes(1)
+
+      clock.removeEventListener('tick', listener)
+      clock.tick(generate(identAlice, 2000, 0))
+
+      expect(listener).toHaveBeenCalledTimes(1) // Still only once
+    })
+  })
+
+  describe('clock synchronization scenarios', () => {
+    it('handles receiving timestamp from faster clock', () => {
+      const clock = new LogicalClock(identAlice)
+
+      // Local clock generates some timestamps
+      clock.now()
+      clock.now()
+
+      // Receive timestamp from remote peer with faster clock
+      const futureTimestamp = generate(identBob, 9999999999, 100)
+      clock.tick(futureTimestamp)
+
+      // Subsequent local timestamps should be after the remote one
+      const nextLocal = clock.now()
+      expect(compare(futureTimestamp, nextLocal)).toBeLessThanOrEqual(0)
+    })
+
+    it('handles receiving timestamp from slower clock', () => {
+      const clock = new LogicalClock(identAlice)
+
+      // Advance local clock significantly
+      const localTs = generate(identAlice, 5000, 0)
+      clock.tick(localTs)
+
+      // Receive old timestamp from slow peer
+      const oldTimestamp = generate(identBob, 1000, 0)
+      clock.tick(oldTimestamp)
+
+      // Clock should not regress
+      expect(clock.latest()).toBe(localTs)
+    })
+
+    it('merges concurrent timestamps by identity', () => {
+      const clock = new LogicalClock(identAlice)
+
+      const ts1 = generate(identAlice, 1000, 0)
+      const ts2 = generate(identBob, 1000, 0)
+
+      clock.tick(ts1)
+      clock.tick(ts2)
+
+      // Latest should be whichever is greater
+      const latest = clock.latest()
+      const ordering = compare(ts1, ts2)
+      if (ordering < 0) {
+        expect(latest).toBe(ts2)
+      } else if (ordering > 0) {
+        expect(latest).toBe(ts1)
+      } else {
+        // Should not be equal with different identities
+        expect(ordering).not.toBe(0)
+      }
+    })
+  })
+
+  describe('backward clock handling', () => {
+    it('maintains monotonicity when system clock goes backward', () => {
+      const clock = new LogicalClock(identAlice)
+
+      // Generate timestamp at current time
+      const ts1 = clock.now()
+      const {seconds: s1} = explode(ts1)
+
+      // Simulate system clock going backward by directly ticking with past timestamp
+      // This tests the clock's resilience but note: now() uses Date.now() which we can't mock easily
+      // So we test the tick behavior instead
+      const oldTimestamp = generate(identAlice, s1 - 100, 0)
+      clock.tick(oldTimestamp)
+
+      // Latest should not regress
+      expect(clock.latest()).toBe(ts1)
+    })
+  })
+
+  describe('bootstrapping from existing timestamp', () => {
+    it('continues from bootstrapped timestamp', () => {
+      const existingTimestamp = generate(identAlice, 5000, 42)
+      const clock = new LogicalClock(identAlice, existingTimestamp)
+
+      const newTimestamp = clock.now()
+
+      // New timestamp should be after the bootstrapped one
+      expect(compare(existingTimestamp, newTimestamp)).toBeLessThanOrEqual(0)
+    })
+
+    it('bootstraps with timestamp from different identity', () => {
+      const bobTimestamp = generate(identBob, 5000, 42)
+      const clock = new LogicalClock(identAlice, bobTimestamp)
+
+      expect(clock.latest()).toBe(bobTimestamp)
+      expect(clock.actor).toBe(identAlice)
+
+      // New timestamps should use alice's identity
+      const newTimestamp = clock.now()
+      const {identid} = explode(newTimestamp)
+      expect(identid).toBe(identAlice)
+    })
+  })
+
+  describe('edge cases', () => {
+    it('handles counter overflow scenario', () => {
+      const clock = new LogicalClock(identAlice)
+      const timestamps = []
+
+      // Generate many timestamps rapidly
+      for (let i = 0; i < 1000; i++) {
+        timestamps.push(clock.now())
+      }
+
+      // All should be strictly ordered
+      for (let i = 0; i < timestamps.length - 1; i++) {
+        expect(compare(timestamps[i], timestamps[i + 1])).toBeLessThan(0)
+      }
+    })
+
+    it('handles timestamp at epoch zero', () => {
+      const clock = new LogicalClock(identAlice)
+      const zeroTimestamp = generate(identAlice, 0, 0)
+
+      clock.tick(zeroTimestamp)
+      expect(clock.latest()).toBe(zeroTimestamp)
+    })
+
+    it('handles very large timestamp values', () => {
+      const clock = new LogicalClock(identAlice)
+      const largeTimestamp = generate(identAlice, 9999999999, 999999)
+
+      clock.tick(largeTimestamp)
+      expect(clock.latest()).toBe(largeTimestamp)
+    })
+  })
+})

src/realm/logical-clock.ts

···
 import {IdentID} from '#realm/protocol/brands'
 import {compare, generate, Timestamp} from '#realm/protocol/timestamp'
 
+/**
+ * A logical clock that generates monotonically increasing timestamps, with identity as tiebreaking.
+ *
+ * @example
+ * ```ts
+ * const identid = IdentBrand.parse('idt_alice')
+ * const clock = new LogicalClock(identid)
+ *
+ * clock.latest //=> null
+ * clock.addEventListener('tick', (event) => {
+ *   console.log('Clock advanced:', event.detail)
+ * })
+ *
+ * const timestamp = clock.now()
+ * // event fired
+ *
+ * clock.latest //=> some timestamp
+ *
+ * // got a timestamp from outside? observe it
+ * clock.tick(receivedTimestamp)
+ * ```
+ */
 export class LogicalClock extends EventTarget {
   #identid: IdentID
   #counter = 0
   #seconds = 0
   #latest: Timestamp | null = null
 
+  /**
+   * Triggered when the clock advances.
+   * @see {@link TickEvent}
+   * @event
+   */
+  static readonly TICK = 'tick'
+
+  /**
+   * @param identid - identity for this clock
+   * @param latest - optional initial timestamp to bootstrap the clock
+   */
   constructor(identid: IdentID, latest: Timestamp | null = null) {
     super()
     this.#identid = identid
···
     return this.#identid
   }
 
+  /**
+   * @returns The latest timestamp, or null if no timestamps have been generated/observed
+   */
   latest(): Timestamp | null {
     return this.#latest
   }
 
+  /**
+   * @returns a new timestamp representing the current moment
+   * @remarks
+   * the generated timestamp is automatically passed to {@link tick} to update the clock state.
+   */
   now(): Timestamp {
     const seconds = Math.round(Date.now() / 1000)
     if (seconds === this.#seconds) {
···
     return this.tick(now)
   }
 
+  /**
+   * updates the clock with an observed timestamp.
+   *
+   * @param timestamp - the timestamp to observe
+   * @returns the current latest timestamp (may or may not be the provided timestamp)
+   *
+   * @remarks
+   * If the provided timestamp is greater than the current latest timestamp,
+   * the clock advances and a 'tick' event is dispatched. If the timestamp is
+   * not newer, the clock state remains unchanged.
+   */
   tick(timestamp: Timestamp) {
     if (!this.#latest || compare(this.#latest, timestamp) < 0) {
       this.#latest = timestamp
-      this.dispatchEvent(new CustomEvent('tick', {detail: timestamp}))
+      this.dispatchEvent(new TickEvent(LogicalClock.TICK, timestamp))
     }
 
     return this.#latest
   }
 }
+
+/**
+ * An event emmitted when the logical clock advances.
+ * @see {@link LogicalClock.tick}
+ * @event
+ */
+export class TickEvent extends CustomEvent<Timestamp> {
+  constructor(name: string, timestamp: Timestamp) {
+    super(name, {detail: timestamp})
+  }
+}

src/realm/protocol/messages-realm.ts

···
 
 export const realmPeerLeftEventSchema = makeEventSchema(
   'realm.peer-left',
-  z.object({identid: IdentBrand.schema,}),
+  z.object({identid: IdentBrand.schema}),
 )
 
 ///

src/realm/protocol/timestamp.spec.ts

···
+import {describe, expect, it} from '@jest/globals'
+import {IdentBrand} from './brands'
+import {compare, explode, generate, logicalClockSchema} from './timestamp'
+
+describe('timestamp utilities', () => {
+  describe('generate', () => {
+    it('creates a valid timestamp with correct format', () => {
+      const identid = IdentBrand.generate()
+      const timestamp = generate(identid, 1699564800, 42)
+
+      expect(timestamp).toMatch(/^lc:1699564800:000042:idt\..+$/)
+      expect(timestamp).toContain(identid)
+    })
+
+    it('pads counter with zeros to 6 digits', () => {
+      const identid = IdentBrand.generate()
+
+      expect(generate(identid, 1000, 0)).toContain('lc:1000:000000:')
+      expect(generate(identid, 1000, 1)).toContain('lc:1000:000001:')
+      expect(generate(identid, 1000, 999)).toContain('lc:1000:000999:')
+      expect(generate(identid, 1000, 999999)).toContain('lc:1000:999999:')
+    })
+
+    it('handles large second values', () => {
+      const identid = IdentBrand.generate()
+      const largeSeconds = 1699564800
+
+      const timestamp = generate(identid, largeSeconds, 0)
+      expect(timestamp).toContain('lc:1699564800:')
+    })
+
+    it('returns a branded timestamp that validates against schema', () => {
+      const identid = IdentBrand.generate()
+      const timestamp = generate(identid, 1699564800, 42)
+
+      expect(() => logicalClockSchema.parse(timestamp)).not.toThrow()
+    })
+  })
+
+  describe('explode', () => {
+    it('decomposes a timestamp into its parts', () => {
+      const identid = IdentBrand.generate()
+      const timestamp = generate(identid, 1699564800, 42)
+
+      const {identid: extractedId, seconds, counter} = explode(timestamp)
+
+      expect(extractedId).toBe(identid)
+      expect(seconds).toBe(1699564800)
+      expect(counter).toBe(42)
+    })
+
+    it('correctly parses zero values', () => {
+      const identid = IdentBrand.generate()
+      const timestamp = generate(identid, 0, 0)
+
+      const {seconds, counter} = explode(timestamp)
+
+      expect(seconds).toBe(0)
+      expect(counter).toBe(0)
+    })
+
+    it('handles maximum counter values', () => {
+      const identid = IdentBrand.generate()
+      const timestamp = generate(identid, 1000, 999999)
+
+      const {counter} = explode(timestamp)
+
+      expect(counter).toBe(999999)
+    })
+  })
+
+  describe('compare', () => {
+    const identAlice = IdentBrand.generate()
+    const identBob = IdentBrand.generate()
+
+    it('returns negative when first timestamp is earlier (by seconds)', () => {
+      const ts1 = generate(identAlice, 1000, 0)
+      const ts2 = generate(identAlice, 2000, 0)
+
+      expect(compare(ts1, ts2)).toBeLessThan(0)
+    })
+
+    it('returns positive when first timestamp is later (by seconds)', () => {
+      const ts1 = generate(identAlice, 2000, 0)
+      const ts2 = generate(identAlice, 1000, 0)
+
+      expect(compare(ts1, ts2)).toBeGreaterThan(0)
+    })
+
+    it('compares by counter when seconds are equal', () => {
+      const ts1 = generate(identAlice, 1000, 5)
+      const ts2 = generate(identAlice, 1000, 10)
+
+      expect(compare(ts1, ts2)).toBeLessThan(0)
+      expect(compare(ts2, ts1)).toBeGreaterThan(0)
+    })
+
+    it('compares by identid when seconds and counter are equal', () => {
+      const ts1 = generate(identAlice, 1000, 5)
+      const ts2 = generate(identBob, 1000, 5)
+
+      const result = compare(ts1, ts2)
+
+      // Result depends on lexicographic ordering of identids
+      // Consistency: comparing in reverse should give opposite sign
+
+      expect(result).not.toBe(0)
+      expect(Math.sign(result)).toBe(-Math.sign(compare(ts2, ts1)))
+    })
+
+    it('returns zero for identical timestamps', () => {
+      const ts1 = generate(identAlice, 1000, 5)
+      const ts2 = generate(identAlice, 1000, 5)
+
+      expect(compare(ts1, ts2)).toBe(0)
+    })
+
+    it('provides total ordering (transitivity)', () => {
+      const ts1 = generate(identAlice, 1000, 1)
+      const ts2 = generate(identAlice, 1000, 2)
+      const ts3 = generate(identAlice, 1000, 3)
+
+      // If ts1 < ts2 and ts2 < ts3, then ts1 < ts3
+      expect(compare(ts1, ts2)).toBeLessThan(0)
+      expect(compare(ts2, ts3)).toBeLessThan(0)
+      expect(compare(ts1, ts3)).toBeLessThan(0)
+    })
+
+    it('seconds take precedence over counter', () => {
+      const ts1 = generate(identAlice, 1000, 999999)
+      const ts2 = generate(identAlice, 1001, 0)
+
+      expect(compare(ts1, ts2)).toBeLessThan(0)
+    })
+
+    it('counter takes precedence over identid', () => {
+      const ts1 = generate(identBob, 1000, 5) // identBob might be > identAlice lexically
+      const ts2 = generate(identAlice, 1000, 10)
+
+      expect(compare(ts1, ts2)).toBeLessThan(0)
+    })
+  })
+
+  describe('logicalClockSchema', () => {
+    it('validates correct timestamp format', () => {
+      const identid = IdentBrand.generate()
+      const validTimestamp = generate(identid, 1699564800, 42)
+
+      expect(() => logicalClockSchema.parse(validTimestamp)).not.toThrow()
+    })
+
+    it('rejects invalid format', () => {
+      expect(() => logicalClockSchema.parse('invalid')).toThrow()
+      expect(() => logicalClockSchema.parse('lc:abc:def:ghi')).toThrow()
+    })
+
+    it('rejects incorrect prefix', () => {
+      const identid = IdentBrand.generate()
+      const badTimestamp = `hlc:1000:000042:${identid}`
+
+      expect(() => logicalClockSchema.parse(badTimestamp)).toThrow()
+    })
+
+    it('validates counter padding', () => {
+      const identid = IdentBrand.generate()
+
+      expect(() => logicalClockSchema.parse(`lc:1000:000042:${identid}`)).not.toThrow()
+      expect(() => logicalClockSchema.parse(`lc:1000:42:${identid}`)).toThrow()
+      expect(() => logicalClockSchema.parse(`lc:1000:0042:${identid}`)).toThrow()
+    })
+  })
+
+  describe('round-trip consistency', () => {
+    it('generate and explode are inverse operations', () => {
+      const identid = IdentBrand.generate()
+      const originalSeconds = 1699564800
+      const originalCounter = 42
+
+      const timestamp = generate(identid, originalSeconds, originalCounter)
+      const {identid: extractedId, seconds, counter} = explode(timestamp)
+
+      expect(extractedId).toBe(identid)
+      expect(seconds).toBe(originalSeconds)
+      expect(counter).toBe(originalCounter)
+    })
+
+    it('handles edge cases in round-trip', () => {
+      const identid = IdentBrand.generate()
+      const testCases = [
+        [0, 0],
+        [1, 1],
+        [999999, 999999],
+        [1699564800, 123456],
+      ]
+
+      for (const [seconds, counter] of testCases) {
+        const timestamp = generate(identid, seconds, counter)
+        const exploded = explode(timestamp)
+
+        expect(exploded.identid).toBe(identid)
+        expect(exploded.seconds).toBe(seconds)
+        expect(exploded.counter).toBe(counter)
+      }
+    })
+  })
+})

src/realm/protocol/timestamp.ts

···
 const pattern = `lc:\\d+:\\d{6}:${IdentBrand.pattern}`
 const regexp = new RegExp(`^${pattern}`)
 
-// hlc format: 'lc.seconds.counter.identid'
-
 export const logicalClockSchema = z.string().regex(regexp).brand(Symbol('hlc'))
 export type Timestamp = z.infer<typeof logicalClockSchema>
 
 export const peerClocksSchema = z.record(z.string(), logicalClockSchema.nullable())
 export type PeerClocks = z.infer<typeof peerClocksSchema>
 
+/**
+ * generates a new logical clock timestamp
+ *
+ * @param identid - The unique identifier of the actor/node creating the timestamp
+ * @param seconds - Unix timestamp in seconds
+ * @param counter - Sub-second counter for ordering events within the same second (0-999999)
+ * @returns a valid logical clock timestamp
+ */
 export function generate(identid: IdentID, seconds: number, counter: number) {
   const counterstr = String(counter).padStart(6, '0')
-  const secondsstr = seconds.toFixed(0).padStart(6, '0')
+  const secondsstr = seconds.toFixed(0)
 
   const hlcstr = `lc:${secondsstr}:${counterstr}:${identid}`
   return logicalClockSchema.parse(hlcstr) // adds the brand
 }
 
+/**
+ * explodes a logical clock timestamp into its constituent parts.
+ *
+ * @param input - The timestamp to decompose
+ * @returns the exploded data
+ */
 export function explode(input: Timestamp): {identid: IdentID; seconds: number; counter: number} {
   const [_a, _seconds, _counter, _identid] = input.split(':')
   const seconds = Number(_seconds)
···
   return {seconds, counter, identid}
 }
 
+/**
+ * compares two logical clock timestamps to determine their ordering.
+ * timestamp identities are used for tiebreaking
+ *
+ * @param a - timestamp to compare
+ * @param b - timestamp to compare
+ * @returns Negative if a \< b, positive if a \> b, zero if equal
+ *
+ * @example
+ * ```ts
+ * const ts1 = logicalClockSchema.parse('lc:1699564800:000042:idt_alice')
+ * const ts2 = logicalClockSchema.parse('lc:1699564800:000043:idt_bob')
+ * compare(ts1, ts2) // Returns negative (ts1 happened before ts2)
+ * ```
+ */
 export function compare(a: Timestamp, b: Timestamp): number {
   const [_a, asec, acounter, aident] = a.split(':')
   const [_b, bsec, bcounter, bident] = b.split(':')